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PREFACE 


The purpose of the FORTH ENCYCLOPEDIA is to make available in one location all of the information necessary to use and understand 
each individual word in the FORTH language. It is useful for everyone from FORTH beginners to FORTH experts. Just like any other 
programmer's manual, this book is a tool which allows the programmer to spend more time "solving the problem" and less time "fighting 
the language." 

As FORTH programmers, we saw a need for documentation that would explain in one place everything one needed to know about a 
FORTH word. It is our intent to relieve the programmer of the burden of sifting through multiple sources and/or FORTH code in order to 
understand a desired FORTH definition. 


The specific implementation documented is the 8080 Version 1.1 (CP/M) fig-Model. However, the usefulness of this book is not limited to 
just this implementation. Indeed, even non-fig-FORTH programmers will find it a useful reference. The activity of each definition is 
both literally and conceptually described. Each definition references FORTH-79. Those words which have two or more activities 
(defining words and compiler words) have all activities described in detail. The low-level code primitives are described in "generic" 
terms common to all assembly languages. 




»-U ^ An : 1 


In summary, this book is truly a FORTH ,? &icy eloped la" as it provides mfori nation ranging trom the ove 
each definition. The acceptance of FORTH in the software community has been limited by a lack of this type of documentation. We 
hope this and other recent publications will help satisfy that need. 
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HOW THIS BOOK IS ORGANIZED 


Each word (or "definition") description follows this general format: 

1. Word Name (Parameter Stack Activity) 

2. Text Section 

a. Word Pronounciation 

b. General Description 

c. Detailed Description 

d. Example 

3. Formal Parameters 

4. High or Low Level Statement 

5. Likely Error Messages 

6. "Refer to" List 

7. FORTH-79 

8. Flowchart Section 

a. High Level Flowchart (if applicable) 

b. Detailed Flowchart 

1. Word Name (Parameter Stack Activity) -- The first line of each description is printed in bold characters. The definition name is on 
the left followed by the parameter stack activity enclosed in parentheses. The general format for parameter stack entries is: 

( before execution -- after execution ) 

When multiple stack parameters are listed, each entry is separated by a The lefthand entry is lowest on the stack, the righthand 
entry is the top of the parameter stack. 

HINT: By pronouncing as "under" and " as "leaves" this horizontal stack format is quite readable. For example: 

( valuel \ value2 -- value3 ) becomes "valuel under value2 leaves value3" 

Some definitions return different stack conditions depending upon their input (for example, successful or unsuccessful completion of a 
word). In these cases, each condition is listed separately. 

Normally the stack parameters described reflect the "execution time" (Sequence 3) action of a word. (See "Definition of Sequence 
Times" Section.) If a word has more than one action (e.g., execution time and compile time action), the stack parameters for each 
activity are listed separately. 

2. Text Section 

a. Word Pronounciation - Since FORTH is intended to be a speakable language, the pronunciation (if necessary) is given inside 
parentheses. 

b. General Description - The first part of the text section is usually a summary of the purpose of the definition. 

c. Detailed Description - This section is the pertinent information concerning the word. 

Compiler and defining words have two sets of actions and therefore the description of this category of words is divided into two 
sections. The compile time action is listed followed by the execution time action. 

d. Example - An example of a word which uses the described word is usually included. 

3. Formal Parameters - This section contains a description of the "at entry" and "at exit" parameter stack entries for the definition. 
This normally reflects the execution time action of a word. Words with more than one action have parameters for each action listed 
separately. 

If no stack parameters are present, "at entry" or "at exit" is followed by the phrase "No parameters". 

The activity of some words affect more than just the parameter stack. In those instances, all other affected parameters are also 
described. 

4. High or Low Level Statement - This states whether the word is a high level definition (comprised of other FORTH definitions) or an 
assembly langnagecode primitive. 

5. Likely Error Messages - This section describes the error messages which are most likely to occur when using this word. (Only the 
most likely messages are listed because serious error conditions can cause indeterminable error messages.) 

6. "Refer to" List - Lists words to refer to for more information. 

7. FORTH-79 - This shows how the described word relates to the FORTH-79 Standard. 
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8. Flowchart Section - All flowcharts use the following format: 

The flowcharts are generally divided into three columns. The leftmost column contains word names and labels. The middle column 
contains a formal definition of the activity of the word. The rightmost column contains branch labels and comments describing the 
activity of this word as it relates to the definition being discussed. 

A right square bracket, located on the far right of the comment column, encloses those words which would normally be grouped 
together as a FORTH phrase. A phrase in FORTH is a logical grouping of words which when combined together produce a desired 
result. 

The larger, more complex words may also be divided into groupings analogous to sentences in English. These sentences are proceeded 
by a comment enclosed in curly brackets. 

The more complex flowcharts are accompanied by a high level (macro) flowchart so the overall action of the definition can easily be 
grasped. Each box in the macro flowchart roughly corresponds to a curly bracket section of the detailed flowcharts. 

The same general format is followed for the low level code primitives. Code definitions must always terminate with an eventual jump 
to NEXT . This is shown with a dashed line extending across all three columns. 

ABORT vs. QUIT: 


Either an ABORT or a QUIT may occur when an error condition arises. The contents of the user variable WARNING determines which 
action is taken. Flowchart references assume that a QUIT will occur. 
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DEFINITION OF SEQUENCE TIMES 


One of the major philosophical differences between FORTH and the more traditional programming languages is the fact that the FORTH 
compiler is itself composed of FORTH words. This compiler may also be extended at any time with the addition of new compiler words; 
this causes a special set of problems to arise. 

Specifically: 

What is a word doing at any given time? 

Is it being defined? 

Is it being compiled? 

Is it executing? 

This ambiguity is made clear through the use of the terms Sequence 1, Sequence 2, and Sequence 3. These sequences will be described in 
ascending order of complexity. 

Sequence 3: 

The purpose of all FORTH definitions is to eventually execute. The act of executing is termed a definition's "run time" or "execution 
time" or "Sequence 3" action. For example, dropping a value from the top of the parameter stack is the "run time" (Sequence 3) action of 
the word DROP . 

Sequence 2: 

In order to be able to execute, a definition must first be compiled or assembled. The act of being compiled or assembled, then, is the 
"Sequence 2" time for the word being compiled. e.g., The Sequence 2 time for DROP is when DROP is being compiled. 

Confusion often arises when one considers the action of the compiler words themselves. Compiler words must execute in order to 
compile a definition. i.e., Compiler words execute (the compiler word's Sequence 3 time) during the Sequence 2 time of the word being 
compiled. 

Compiler words normally have two sets of actions described; those at compile time (Sequence 2) and those at execution time (Sequence 
3). The most common compiler words are control structure words such as ELSE . ELSE is used within a definition (FROG for example) to 
produce a specific action when that word, FROG, is executed at its Sequence 3 time. This action is the Sequence 3 action of ELSc. . But, 
in order for ELSE to be able to correctly perform this desired action, certain manipulations must be performed when FROG is being 
compiled (at FROG's Sequence 2). The code within ELSE which performs these compile time manipulations determines the Sequence 2 
action of ELSE . This dual action is true for all compiler words. 


Sequence 1: 

There are groups or types of words in FORTH which are defining words. (Defining words are generally classified as words which do not 
execute in the system "compile" state and which directly use the word CREATE (and not : ) to begin creating a aenmtion.) inese woros 
create compiler definitions, or "parents", which when executed at compile time (Sequence 2) create "children" definitions which then 
execute (Sequence 3) to perform some task. "Parent" definitions (e.g., VOCABULARY) are created at the parentis Sequence 1 time. 
"Child" definitions (e.g., FORTH ) are compiled via the "parent" at the "child's Sequence 2 time. The "child" then executes at rts own 
Sequence 3 time (e.g., when FORTH executes, FORTH is made the CONTEXT vocabulary). 


Always bear in mind that the Sequence time of any definition is relative to itself. It is perfectly legal and necessary for compiler words 
to be executing (Sequence 3) while a definition is being created (Sequence 1 or Sequence 2). 


Some compiler words purposely switch the system back and forth between states while all the time remaining in t e 
definition-being-compiled's Sequence 2 time. At any given time the "state" the system is in may be either "interpretation state or 
"compilation" state. Do not confuse the overall Sequence time action of a definition with the "state" of the system. 
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1 ( value\ address — ) 

(pronounced "store") stores the 16-bit value located in the second parameter stack entry into the memory location specified by the top 
parameter stack entry. 

Cl is the word used to store 8-bit (or byte or character) values. 

(§ has the opposite effect of 1 . 

* At entry - The top of the parameter stack contains the 16-bit address specifying the memory location the value is to be 
stored into. The second stack entry contains the 16-bit value. 

* At exit - No parameters. 

1 is a low level code primitive. 

Refer to Cl . and (a) . 

FORTH-79: The FORTH-79 equivalent for 1 is 1 . 



NEXT 
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!CSP 


1CSP ( - ) 

•CSP (pronounced "store-C-S-P") saves the current parameter stack address in the user variable CSP . This word is used in conjunction 
with ?CSP to determine if the parameter stack has become unbalanced due to a compilation error. 

An example of the use of '.CSP can be found in : . 

* At entry - No parameters. 

* At exit - No parameters. 

1CSP is a high level colon definition. 

Refer to ?CSP . 

FORTH-79: There is no FORTH-79 equivalent for 1CSP . 

Definition: : .'CSP ( - ) SPfa! CSP 1 ; 


DOCOL 


spta 


CSP 


;S 



Get the address of the 
next available 
parameter stack 
location. 
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# ( double precision value — dottle precisian quotient) ff 

# (pronounced "sharp") performs a binary-to-ascii conversion of one digit of a double precision value into an ascii character that is placed 
into a pictured numeric output string. This output string is built downward starting from one byte before PAD . The conversion proceeds 
from right to left (low order digit to high order digit) with one "column" being converted each time // is executed. That is, the first time 

# is executed, the units digit is converted; the next, the tens digit; the next, the hundreds digit; etc. 

One digit is converted each time # is executed. # uses the current BASE value as the conversion radix. The double precision value is 
divided by the radix. The remainder is converted to an ascii digit; the quotient remains on the stack. <# must first be executed to set up 
for # . # is used in the general form <// # //> to convert single digits. The form <# // // ... //> is used to convert as many digits as 
specified. (Refer to //S for converting an entire double precision number at one time.) 


A double precision input value of zero simply results in an ascii output digit of zero. 

D.R is an example of a word that uses pictured numeric output. #S is an example of a word that uses // . 


* At entry - The top of the parameter stack contains an unsigned 32-bit double precision value with the high order portion in 
the first stack entry and the low order portion in the second entry. 

Note: # wiil actually oniy convert a positive double precision vaiue (i.e., only 31 bits). Therefore a DABS should normally 
precede the <# in a pictured numeric expression to convert negative double precision values to their absolute value. SIGN 
is used to display the sign. 

BASE contains the radix to be used in conversion. 

* At exit - The top of the parameter stack contains the quotient of the original value divided by BASE in the form of a 
32-bit unsigned double precision value with the high order portion in the first stack entry and the low order portion in the 
second stack entry. 

Characters will be placed into memory from high to low memory starting at the beginning of PAD and working toward the end of the 
dictionary. HLD points to the last character converted. 


# is a high level colon definition. 

Refer to <# , #> , #S , HOLD , SIGN , HLD , BASE , and PAD . 

FORTH-79: The FORTH-79 equivalent for # is // . 

Definition: : # ( Dvalue - Dquotient ) 

BASE (a) M/MOD ROT 9 OVER < 
F 7 + THEN 30 + HOLD ; 


DOCOL 


BASE 


@ 


M/MOD 


ROT 



Set up for (a) . _ | 


Get the current base. 
Set up for M/MOD . 


Divide the value by 
BASE . Leave the 
quotient on the stack 
with the remainder 
(which will be 
converted to ascii) 
below it. 


Put the remainder onto 
the top of the 
parameter stack. 


LIT 

09H 


OVER 


< 


IF 
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The remainder was 
greater than 9 so 
convert it to alpha 
(e.g., Hex A). 


Add 7 to the remainder 
so it will be alpha 
when ascii conversion 
occurs. 

This is the entry point 
for the "false portion" 
of the previous IF that 
tested for alpha. 

Set up for + . 


Add 30 H to the 
remainder to create the 
ascii character 0-9 or 
A-F. (Actually any base 
can be used; base 17 
would allow the letter 
G also.) 


Move the ascii'ed 
character to PAD . One 
character to the left 
of the previous one. 



4 








#> 


( double precision value — 


address\ count) 


#> 


#> (pronounced "sharp-qreater-than") terminates a pictured numeric conversion expression. #> drops the double precision conversion 
value left by it and replaces it with the beginning address of the converted character string and the string length (in a format suitable for 


TYPE ). 


#> is used in the general form: 


<it it it> 


D.R is an example of a word that uses pictured numeric output. 

* At entry - The top of the parameter stack contains a double precision value occupying the first and second stack entries. 
HLD points to the beginning of a converted pictured numeric character string. 

* At exit - The top of the parameter stack contains an address pointing to the beginning of the converted pictured numeric 
character string. The second parameter stack entry contains the character count of the string. 

#> is a high level colon definition. 


Refer to <# , it , it S , HOLD , HLD , SIGN , and PAD . 

FORTH-79: The FORTH-79 equivalent for #> is it> . 

Definition: : it> ( Dvalue - addr\count) 

DROP DROP HLD fal PAD OVER - 


DOCOL 


DROP 


DROP 


HLD 


i 


PAD 


OVER 



Drop the double 
precision value left 
over from it from the 
stack. 


Set up for (§ . HLD 
points at the last 
character converted. 


Pick up the beginning 
address of the 
converted character 
string. (This is 
actually the last 
character converted.) 


Set up to calculate 
character count. PAD 
represents the end of 
the converted character 
string (i.e., conversion 
went from PAD toward 
low memory). 


Set up for - . 

Duplicate the beginning 
string address. 



Calculate the length of 
the converted character 
string. 
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#s 


#S ( unsigned double precision value — o\ 0 ) 

//S (pronounced "sharp-S") performs a binary-to-ascii conversion of a double precision value into an ascii pictured numeric output 
character string. This character string is created in memory, starting at one byte before PAD and working downward towards low 
memory. The word performs a // conversion until the original double precision value is completely converted to ascii. Actually // is 
called repeatedly until conversion is complete (i.e., the resulting quotient is double precision zero). 


//S is used within a <# #> expression. D.R is an example of a word that uses #S for pictured numeric output. 


* At entry - The top of the parameter stack contains an unsigned 32-bit double precision value which is to be converted 
from binary to ascii. The high order portion is in the first stack entry and the low order portion is in the second entry. 

BASE contains the radix to be used in the conversion. 

* At exit - The first and second parameter stack entries contain a double precision value of zero. 

Converted ascii characters are located in memory. HLD points to the last character converted. 


#S is a high level colon definition. 

Refer to <# , // , //> , SIGN , HOLD , HLD , and PAD . 


FORTH-79: The FORTH-79 equivalent for //S is #S . 


Definition: : //S ( Dunsigned value -00) 

BEGIN // OVER OVER OR 0 = UNTIL ; 



This is the entry point 

for the "repeat portion" UNTIL 

of the BEGIN-UNTIL 

structure. 


Convert the digit and 
place its ascii value 
into memory. HLD will 
be aimed at the 
character. 

;S 

Set up for OR . 

Duplicate the low order 
portion of the double 
precision value. 


Set up for OR . 
Duplicate the high 
order portion of the 
double precision value. 


Set up for 0= . Both 
words must be 0 or a 
non-zero logical value 
will result, i.e., The 
truth flag will be 
true. 
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COMPILE STATE: (-) 
(Sequence 2) 


EXECUTION STATE: 
(Sequence 3) 

! (pronounced “tick") 
stack. In compilation 


( — address of specified word ) 

in execution state, ! piaces the Parameter Field Address of a specified definition onto the top of the parameter 
state it compiles the address into the dictionary. It is used in the form: 

' nnnn 


where nnrm is the name of the desired word. 

Since LITERAL is used within the definition, the word exhibits two characteristics: 

1. If the system is in compilation state, the address is compiled into the dictionary as a literal. 

2. If the system is in execution state, the address is left on the top of the parameter stack. 

' searches both the CONTEXT and CURRENT vocabularies. If the specified word is not found, Error Message 0 ("?") is issued and a QUIT 
occurs. 

-FIND is the basis of ' since it performs the necessary dictionary search. 

Note that ' is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 

COMPILE STATE (Sequence 2): 

* At entry - No parameters. 

* At exit - The address is compiled as a literal into the definition being compiled. No parameters on the paramater stack. 
EXECUTION STATE (Sequence 3): 

* At entry - No parameters. 

* At exit - The address of the specified word is on the top of the parameter stack. 

LIKELY ERROR MESSAGES: 

? pronounced "HUH?" (0) — The word in question cannot be found in the dictionary. 

' is a high level colon definition. 

Refer to -FIND . 


FORTH-79: The FORTH-79 equivalent for ' is '. 


Definition: 


( — addr ) 

-FIND 0= 0 ERROR DROP TCOMPILE ] LITERAL ; IMMEDIATE 


DOCOL 


-FIND 


0 = 



Look for a dictionary 
match on the specified 
word. TOS is set true 
(1) if a match is 
found; otherwise, it is 
set to false (0). 


Set up for TERROR . 
Leave a true flag if a 
match was not found. 
(Reverse the flag left 
by -FIND .) 


0 


TERROR 


DROP 



Set up for TERROR . 

0 is the error message 
number for "no match' 
during a search. 

Issue Error Message 0 
("?") if no match 
occurred. 

NOTE: If an error 
message is issued, a 
QUIT will occur and 
execution will cease 
here. _ 


In this case, the 
length byte of the 
specified word. 
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[COMPILE ] 


LITERAL 


;s 


IMMEDIATE 



Since LITERAL is an 
IMMEDIATE word, 
[COMPILE ] must be 
used to compile it into 
the definition. (Other¬ 
wise, it would execute 
:_ 

11 IDLCdU U I LIC II ty 

compiled. [COMPILE] is 
only used at Sequence 1 
time to "compile" 
LITERAL into ' and 
does not exist in''s 
(tick's) definition 
when ' is executed at 
compile time (Sequence 
2 ). 


Compile the found 
address into the 
dictionary 

or 

leave the address on 
the top of the stack. 


' is a compiler word 
and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 
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( (pronounced "left paren") is used to denote the beginning of a comment. It is used in the form: 

( comment) 

Note that ( is a FORTH word and therefore must be separated from the comment string by at least one blank. The comment must be 
terminated by a ) ("right paren"). The terminating right parenthesis does not have to be preceded by a blank. Comments may appear 
inside or outside of a definition. 

The basis of ( is WORD . WORD is given the ascii value of ")" for an input delimiter parameter. WORD then keeps reading (and ignoring) 
text until encountering a ")" character. 

Note that ( is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 

* At entry - No parameters. 

* At exit - No parameters, 

( is a high level colon definition. 

FORTH-79: The FORTH-79 eguivalent for ( is ( . 

Definition: : ( ( —) 

29 WORD ; IMMEDIATE 


DOCOL 


LIT 

29H 


WORD 


IMMEDIATE 



Put ascii ")" (29H) 
onto the top of the 
stack as a delimiter 
for WORD. 

NOTE: Since WORD 
does not advance the 
dictionary pointer 
(DP), the comment is in 
effect ignored by the 
system. 


( is a compiler word 
and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 
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(.") Return Stack ( address — address ) 

(.") (pronounced "paren-dot-quote") is the run-time procedure compiled by . Its purpose is to output the text string compiled into the 
dictionary by . 

(.") performs two basic functions: 

1. (.") prints the character string compiled into the dictionary by . 

2. (.") increments the IP past the character string so that interpretation begins with the word following the string. 

An example would be the printing of the characters "ABD" via the word (e.g., ABD" ). The following would be compiled into the 
dictionary by . 



(.") will first execute COUNT to set up the parameter stack for TYPE ; then it will increment the value on the return stack (which points 
to the next definition to be interpreted) to point to the "next definition's CFA". 

* At entry - The top of the return stack contains the address of the length byte of the text string. (This address is normally 
that of the next word to be executed but the text string is compiled "in line" and therefore immediately follows the 
execution address of (.") .) 

* At exit - The top of the return stack contains the address of the next word to interpret. 

(.") is a high level colon definition. 

(.") may only be used inside of a colon definition. 

Refer to ." . 


FORTH-79: There is no FORTH-79 equivalent for (.") . 


Definition: : (.") ( — ) 

R COUNT DUP 1+ R> + >R TYPE ; 


DOCOL 


R 


COUNT 



Get the address of the 
string's length byte. 
This is normally the 
address of the next 
address to be 
interpreted. In this 
case, though, it is the 
address of the 
beginning of the 
string. 


Set up for TYPE . 


DUP 


1 + 


R> 


>R 



Aim IP at the beginning 
string address. Set up 
to increment IP to aim 
at the next word to be 
interpreted. 


Include the string 
length byte in the 
number of memory 
locations to be skipped 
over. 


Get the address of the 
text string's length 
byte from the return 
stack. 


Calculate the address 
of the next word to 
interpret. 


Put the calculated 
address back onto the 
return stack. 
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TYPE 


;S 



Using the parameters 
supplied by the 
previous COUNT . 
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(+ LOOP) 

(+LOOP) ( increment value — ) 

(+LOOP) (pronounced "paren-plus-loop") is the execution time (Sequence 3) procedure for +LOOP . During compile time (Sequence 2), 
+LOOP compiles the CFA of (+LOOP) into the definition being created. 

The purpose of (+LOOP) is to serve as the run time end of a DO +LOOP sturcture. In doing so, it performs four primary functions: 

1. (+LOOP) obtains the loop increment value from the top of the parameter stack. 

2. (+LOOP) increments the loop Index by the increment value. Note that this value can be either positive or negative. 

3. (+LOOP) performs a signed comparison of the newly calculated loop Index and the loop Limit. 

4. (+LOOP) executes a branch back to the "DO" portion of the structure until the Index is either equal to or greater than the Limit 
when incrementing by a positive value or when the Index is greater than the Limit when incrementing by a negative value. 

When either of these conditions occur, the Index and Limit are dropped from the return stack and execution continues with the word 
after the DO +LOOP . 

(+LOOP) differs from (LOOP) only in that the increment value is provided on the top of the parameter stack instead of defaulting to a 
value of 1. Therefore, the code for (+LOOP) simply picks up the increment value from the parameter stack and jumps into the (LOOP) 
routine immediately after (LOOP) defaulted to an increment value of 1. (Note that this refers to the 8080 fig-FORTH Version 1.1 and 
differs from the fig-Model.) 

Refer to +LOOP for a more high level description of the action of a DO +LOOP structure. 

* At entry - The top of the parameter stack contains a signed 16-bit single precision increment value. Note that this value 
may be negative. The top of the return stack contains the signed 16-bit Index value. The second return stack entry 
contains the 16-bit signed Limit value. 

* At exit to DO portion of loop - No parameter stack parameters. The return stack contains the current Index value in the 
top entry and the original Limit value in the second entry. 

* At exit from DO +LOOP - No parameter stack parameters. The Index and Limit values are dropped from the return 
stack. 

(+LOOP) is a low level code primitive. 

Refer to +LOOP , DO , and (LOOP) . 

FORTH-79: There is no FORTH-79 equivalent for (+LOOP) . 


8080 fig-FORTH 
Version 1.1 



Pop increment value 
from top of parameter 
stack. 


(jMP XLOOl) 


Note this differs from 
the fig-Model. 


Refer to (LOOP). 

Note this is an entry 
point in the code for 
(LOOP) as mentioned in 
description of (+LOOP) . 
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(;CODE) ( -) 


(;CODE) 

(;CODE) (pronounced "paren-semicoIon-code") is a word normally used during Sequence 2 compilation. Its purpose is to compile the 
beginning address of the assembly language code (which must physically immediately follow (;CODE)) into the Code Field of the 
definition being compiled. 

(;CODE) is actually the run time procedure for ;CODE . ;CODE is usually executed at Sequence 1 when defining a "parent" word. The 
"parent" defining word is then executed at Sequence 2 time to create "child" definitions. 

Refer to ;CODE for a complete description of this "parent"/"child" relationship and the use of ;CODE . 

* At entry - No parameter stack parameters. The top of the return stack contains the address of the machine language code 
to be executed. The second word on the return stack contains the address of the procedure that control should be returned 
to after execution. Note this is the reason that definitions ending in ;CODE (assembly language) do not need to be ended 
with a ; . 

* At exit - No parameter stack parameters. The two return stack parameters are dropped from the return stack . 

(;CGDE) is a high ievei colon definition. 


Refer to ;CODE . 

FORTH-79: There is no FORTH-79 equivalent for (;CODE) . 


Definition: : ( ; CODE) ( --) 

| R> LATEST PFA CFA 


DOCOL 


R> 


LATEST 


PFA 


CFA 


;S 



NOTE: In this case, the 
next IP position will 
be the beginning 
address of the machine 
code to be executed. 

i.e., Get address of 
machine code. 


Store the beginning 
machine code address 
into the Code Field 
Address of the "latest" 
defined word. 


NOTE: In this case, the 
calling procedure 
returned to is the 
second entry of the 
return stack since the 
machine code address 
was the first. 
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(ABORT) 


(ABORT) ( all stack values — ) 


(ABORT) (pronounced "paren-abort") is an intermediate word used between ERROR and ABORT . It is normally executed when 
WARNING is negative and simply performs an ABORT . 




nrA ADODT 


( A DflD T\ ir> lofonHorl fn K o (-ho MKrwsMt . t-\ ~ D ~~ 1„~ F^C" A A 

V xlj^i \ i / 10 tit co i 1000 co uo u ic tioors 101 aup iicauUi i oi i ui iuu unco* tscpiauniy L! 1 C r-\ I ui n 

routine and setting WARNING to -1 allows the user routine to "get control" when an error occurs. 


k-u ~ 


nuui\ i wiui mat ui d usci uc unci. 


* At entry - The parameter and return stacks may contain any values. 

* At exit (If an ABORT was executed) - Both stacks will be cleared and the system will be set to the execution state. Refer 
to ABORT . 


* At exit (If an ABORT was not executed) - Both stacks are unchanged and no action was taken. 
(ABORT) is a high level colon definition. 


Refer to ABORT , WARNING , and ERROR . 


FORTH-79: There is no FORTH-79 eguivalent for (ABORT) . 

Definition: : ( ABORT) ( — ) 

ABORT ; 


DOCOL 


ABORT 


;s 



Note: ABORT executes 
QUIT so control does 
not really return to 
the caller! 
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(DO) ( Limit \ Index — ) 


(DO) 


(DO) (pronounced "paren-do") is the execution time (Sequence 3) procedure for DO . During compile time (Sequence 2), DO compiles the 
CFA (Code Field Address) of (DO) into the definition being created. 

The purpose of (DO) is to initialize a DO-LOOP structure for execution. It does this by transferring the user supplied Limit and Index 
values from the parameter stack to the return stack. The Limit and Index values can then be accessed by the run time procedures 
(LOOP) and (+LOOP) . 

For example: 


PARAM 

RETURN 

PARAM 

RETURN 

STACK 

STACK 

STACK 

STACK 

Index 

n3 

nl 

Index 

Limit 

n4 

n2 

Limit 

rl 



n3 

n2 



n4 


Before After 

Execution Execution 

Of (DO) Of (DO) 


Note that the Index is the top value both on the parameter stack and on the return stack. 

Also note that when the loop completes, (LOOP) or (+LOOP) have removed the Index and Limit from the return stack. 

* At entry - The top of the parameter stack contains a signed 16-bit single precision Index (or Initial) value. The second 
stack entry contains a signed 16-bit single precision Limit value. (Refer to DO .) 

* At exit - The two parameters, Index and Limit, have been transferred to the return stack in the same order they appeared 
on the parameter stack. 

(DO) is a low level code primitive. 

Refer to DO , LOOP , +LOOP , (LOOP) , and (+LOOP) . 

FORTH-79: There is no FORTH-79 equivalent for (DO) . 


8080 fig-FORTH 
Version 1.1. 


Pick up return stack 
pointer. 
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(FIND) 

(FIND) Successful - ( string addr\ NFA — PFA\ length\ true flag ) 

(FIND) Unsuccessful - ( string addr \ NFA — false flag ) 

(FIND) (pronounced "paren-find") performs a dictionary search starting from a specified Name Field Address. (FIND) then looks for 
match on the character string pointed to by the second stack word, (FIND) will search an entire "branch" of the vocabulary dictionary 
"inwardly" toward the "trunk". The search stops when a 0 Link Field is encountered; usually, but not necessarily at the end of t ie FORT! 
vocabulary. 

* At entry - The top of the parameter stack contains a 16-bit address pointer to the length byte (i.e., the first byte) of a 
Name Field in the dictionary. The second stack entry contains a pointer (NFA) to the character string to be used for 
comparison. The first byte of this string contains the length of the following string. 

* At exit - Successful - The top of the parameter stack contains a boolean true flag (1). The second stack entry contains the 
byte length of the Name Field (with the MSB set denoting the length byte). The third stack entry contains a 16-bit address 
pointer (PFA) to the Parameter Field of the "found" dictionary entry. 

* At exit - Unsuccessful - The top of the parameter stack contains a boolean false (0) flag. 

(FIND) is a low level code primitive. 


Refer to FIND , and VOCABULARY . 


FORTH-79: There is no FORTH-79 equivalent for (FIND) . 



NEXT 


Figure (FIND)-l 

High Level Flowchart of (FIND) 

Each box roughly corresponds to the curly bracket comments in 
the low level flowchart. 
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(pftnT)- 




This is the entry point 
to loop back and 
compare another 
character. 


The lengths were equal, 
J so perform a character 
| by character 
comparison. 


Aim at next char¬ 
acter in Name Field. 


Aim at next char¬ 
acter in comparison 
string. 




Set truth flag as (This is the top of the 

true (1). stack entry upon exit.) 






DPUSH 

Push length onto 


parameter stack. 

HPUSH 

Push truth flag onto 


stack. 

NEXT 



Compare characters 
(ignoring end of 
string bit (MSB)). 


NOTE: fig-FORTH 
dictionary entries have 
MSB set to denote last 
character of Name 
Field. 


^PFIN3~) 



No match, so exit from 
loop. 


^PFIN2) 


Add 5 to Name Field 
Address to obtain 
Parameter Field 
Address. 


Replace top of the 
parameter stack with I 
calculated Parameter! 
Field Address. 




Backup 1 byte in 
Name Field character 
string. 



Pick up the length 
byte. 


No match so far so 
continue iooping and 
look at the next 
character in the Name 
Field. 

Have successfully 
compared all characters 
in the Name Field, 
i.e., Found a 
successful match. Set 
up return parameters 
and exit. 



No match on that Name 
Field, so increment to 
the end of the current 
Name Field, pick up the 
link to the next 
definition, loop back 
and continue comparing. 


Increment to end of 
Name Field. 


i.e., Most significant 
bit set? 


(This will be the third 
stack entry upon exit.) 


Now back up through 
Name Field until aiming 
at length byte. 


NOTE: In the fig- 
FORTH dictionary, the 
MSB of the length field 
is set to 1. 

(This will be the 
second stack entry upon 
exit.) 


Name Field pointer 
j by 1 so now aiming 
at Link Field. 


Pick up link to next 
dictionary entry. 


i.e., Get next Name 
Field Address. 



^PFINl) 


0 Link Field denotes 
end of dictionary 
thread. 


Have reached the end of 
the dictionary without 
a successful comparison. 
Set up "not found" 
parameters and exit. 


Discard address of 
character string to 
compare on._ 
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Set truth flag as (Top of stack entry at 

false (0). exit.) 






HPUSH Push truth flag onto 

parameter stack. 


NEXT 
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(LINE) 


(LINE) ( line # \ screen # — beg line addr\ line length ) 

(LINE) (pronounced "paren-line") converts a specified line number and screen number into the disk buffer address of the specified line. 
The value for the line length used is also returned. The specified screen is read into memory if necessary. (LINE) is used by .LINE to set 
up parameters for TYPE . 


(LINE) performs three basic functions: 


1. (LINE) calculates what block the line is in within the screen. 


2. (LINE) then calculates the absolute block number. 


3. (LINE) then executes BLOCK and calculates the memory address of the line. 


* 


At entry - The top of the parameter stack contains a 
used. The second stack entry contains a signed 16-bit 


signed 16-bit single precision value specifing the screen number to be 

ninnln n^pnioinn wolllO or> OOI fy I nfl 9 11 OP VA/it‘hin t“hp fiPPPPri. 

. Oili^ic piCciOiun rwiuw jr i> .w •* **• — ■ — --- 


* At exit - The top of the parameter stack contains the signed 16-bit single precision byte count of the specified line. The 
second stack entry contains the 16-bit beginning memory address of the specified line. Trailing blanks are included. Use 
-TRAILING to suppress trailing blanks. 


(LINE) is a high level colon definition. 


Refer to .LINE . 

FORTH-79: There is no FORTH-79 equivalent for (LINE) . 

Definition: : (LINE) ( line #\ screen it — beg line addr\line length ) 

>R C/L B/BUF */MOD R> B/SCR * + BLOCK + C/L ; 


DOCOL 


>R 


C/L 


B/BUF 


*/MOD 



R> 


Temporarily save the 
screen number. 


(Calculate the relative! 
<block number of the > 
[line within the screenj 


Put the characters per 
line onto the top of 
the stack. Set up for 
♦/MOD . 


Put number of bytes per 
disk buffer onto the 
top of the stack. Set 
up for */MOD . 


(Line length * line 
number)/number of 
bytes per buffer = 
relative block number 
within screen. 


B/SCR 


BLOCK 



Calculate the block 
number containing the 
^specified line. 

Retrieve specified 
screen number. 


Put the number of 
blocks per editing 
screen onto the top of 
the stack. 


Blocks per screen * 
specified screen number 
= beginning block 
number. 

Beginning block number 
+ relative block number 
within screen = 
absolute block number. 


Go get the address of 
the calculated absolute 
block number. 
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{ Calculate the beginning I 
address of the line. f 


Absolute block address 
+ remainder from 
division (i.e., byte 
displacement of 
specified line) = 
absolute address of 
specified line and 
screen. 


Put the line count 
(length) used onto the 
stack. This sets up the 
count for an eventual 
TYPE . 








(LOOP) 


(LOOP) ( - ) 

(LOOP) (pronounced "paren-loop") is the execution time (Sequence 3) procedure for LOOP . During compile time (Sequence 2), LOOP 
compiles the CFA of (LOOP) into the definition being created. 

The purpose of (LOOP) is to serve as the run time end of a DO-LOOP structure by performing the following functions: 

1. (LOOP) increments the loop Index by 1. 

2. (LOOP) performs a signed comparison on the newly calculated loop Index and the loop Limit. 

3. (LOOP) executes a branch back to the "DO" portion of the structure until the Index is either equal to or greater than the 
Limit. When this condition occurs, the Index and Limit are dropped from the return stack and execution continues ahead. 

(LOOP) only differs from (+LOOP) in that the increment value defaults to 1 in (LOOP) instead of the increment value being provided on 
the top of the stack as for (+LOOP) . 

Refer to LOOP for a more high level description of the action of a DO-LOOP structure. 

* At entry - No parameter stack entries. The top of the return stack contains the 16-bit signed Index value. The second 
return stack entry contains the 16-bit signed limit value. 

* At exit to DO portion of loop - No parameter stack entries. The top of the return stack contains the 16-bit signed current 
Index value. The second return stack entry contains the 16-bit signed original Limit value. 

* At exit from DO-LOOP - No parameter stack parameters. No return stack parameters. 

(LOOP) is a low level code primitive. 

Refer to LOOP , DO , I , and (+LOOP) . 

FORTH-79: There is no FORTH-79 equivalent for (LOOP) . 



8080 fig-FORTH 
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This is the entry point 
for (+LOOP) . (The 
specified increment 
value has been popped 
off of the parameter 
stack.) 
















(NUMBER) 

(NUMBER) ( double number \ string addr — double number\ char addr ) 

(NUMBER) (pronounced "paren-number") converts a string of ascii text beginning at the specified address plus 1 (e.g., the length byte or 
decimal point is skipped over) into a double precision value of the radix specified in BASE . (NUMBER) is used primarily by NUMBER . 

The user variable DPL is incremented to reflect the number of digits encountered to the right of the decimal point, provided that DPL 
has been set to a value other than -1 (refer to NUMBER ). 

* At entry - The top of the parameter stack contains the 16-bit address of the ascii character string to convert. The first 
byte of the character string is ignored. 

The second and third entries on the parameter stack contain a 32-bit double precision value (the most significant word 
being the second entry) into which the converted number is accumulated. This value should be 0 initially, but will be 
shifted left one digit in the radix when the next digit is converted. 

* At exit - The top of the parameter stack contains a 16-bit address which points to the first non-convertible character 
encountered. 

The second and third stack entries contain the converted 32-bit unsigned double precision value. The second stack entry 
contains the high order portion of the value. The third stack entry contains the low order portion. 

(NUMBER) is a high level colon definition. 

Refer to NUMBER . 


FORTH-79: The FORTH-79 equivalent for (NUMBER) is CONVERT . 

Definition: : ( double number\string addr — double number\char addr) 


BEGIN 

WHILE 


REPEAT 


1+ DUP >R Cfa) BASE fa) DIGIT 
SWAP BASE fa) U* DROP ROT BASE fa) 
D+ DPL fa) 1+ IF 1 DPL +'. THEN 
R> 

R> : 



DIGIT 


Entry point for the 
following BEGIN- 
WHILE-REPEAT 
structure. 


First pass through—Aim 
past the character 
string's length byte. 

All other passes— 
Increment to next 
digit. 


Duplicate the address 
so it can be 
temporarily saved. 


Temporarily save the 
digit address. (Will 
later retrieve it just 
before branching back 
to the 1+). 


Pick up a character to 
convert. Set up for 
DIGIT . 


Set up to get base 
value. 


WHILE 


SWAP 


BASE 


U* 


1 


Replace the address 
on the top of the 
parameter stack with 
the 16-bit memory 
contents of that 
address. 

Pick up the current 
numeric conversion 
base. Set up for 

DIGIT . 


Convert the ascii 
character in the 2nd 
parameter stack 
entry to its binary 
equivalent using the 
value on the top of 
the stack as a base 
value. 



A true flag and the 
converted number will 
be left if conversion 
is successful; else, 
only a false flag is 
left. 


$*(PNUM2) 

Branch past the 
"repeat" portion of the 
structure if conversion 
was unsuccessful (i.e., 
exit from loop). 


luel 


Swap the top two 
values on the 
parameter stack. 


Place the address of 
the user variable 
BASE onto the top of 
the parameter stack. 


Conversion was 
successful, so continue 
' and multiply the most f 
significant portion. 

Put the most 
significant numeric 
word onto the top of 
the stack (is double 
precision number). 
NOTE: This puts digit 
as the low order 
portion of the 
multiplicand. 


Set up to get base 
value. 














@ 


u* 


DROP 


ROT 


BASE 


@ 


U* 


D+ 


DPL 



!§ 


1 + 


F 


1 


DPL 



Perform a 
precision a 
of two doul 
precision r» 
the top of 
parameter 

double 

ddition 

jle 

umbers on 
the 

stack. 



Place the 
the user va 
DPL onto t 
the parame 

iddress of 
riable 
he top of 

iter stack. 

— 


Add the result of the 
above U* to the final 
double precision 
number. 


Set up for F . Ask the 
J question: "Was a 
decimal point 
encountered?" 


Set up to determine if 
a decimal point was 
encountered by 
NUMBER . 


THEN 



Entry point from 
"false" branch of 
previous IF statement, 
(i.e., No decimal 
point) 


R> 


Remove the top value 
from the return 
stack and place it 
onto the top of the 
parameter stack. 


Retrieve the digit 
address so can pick up 
next character. 
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PNUMB1 

Branch back to "begin" 
portion of this 
structure and continue, 
(i.e., Loop back and 
convert the next 
character.) 


Entry point from "while" 
portion of this 
structure. 

NOTE: At this point 
conversion was halted 
because a 
non-convertible 
character was 
encountered. 


Retrieve the digit 
address which in this 
case points to the 
non-convertible 
character. 
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* 


* ( valuel \value2 — single product) 

* (pronounced "times") multiplies two signed single precision values and replaces them with their signed single precision product. 

* is simply a M* followed by a DROP to make the result a single precision value. (Note this differs from the fig-Model. The model uses 
U* which is an unsigned multiply.) 

* At entry - The top of the parameter stack contains a signed 16-bit value to be multiplied by the signed 16-bit value in the 
second stack entry. 

* At exit - The top of the parameter stack contains the signed 16-bit single precision product of the input multipliers. 

* is a high level colon definition. 

Refer to M* . 


FORTH-79: The FQRTH-79 equivalent for * is * . 

Definition: : * ( valuel\value2 -- single product) 

M* DROP ; 


DOCOL 


M* 


DROP 


JS 
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Get an intermediate 
double precision 
product. 


Convert the product to 
single precision. 
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*/ 


*/ ( multiplier \ multiplicand \ divisor — quotient) 

*/ (pronounced "times-divide") performs a multiplication and then a division of three 16-bit signed single precision values according to 
the algebraic statement (valuel * value2) / value3. A 16-bit signed single precision quotient is the output of this operation. 

Logically */ is the same as the sequence: 


valuel value2 * value3 / 

but ♦/ carries the result of the multiplication as a 32-bit signed double precision intermediate result. This allows greater accuracy than 
if a single precision intermediate product was used. 

The basis of */ is */MOD . */ drops the remainder generated by */MOD . If a remainder is desired, use */MOD . 

* At entry - The parameter stack contains three 16-bit signed single precision values. The second and third stack entries 
are to be multiplied together with the resulting product divided by the 16-bit signed single precision value on the top of 
the parameter stack. 

* At exit - The top of the parameter stack contains a 16-bit signed single precision quotient. 

♦/ is a high level colon definition. 

Refer to */MOD . 

FORTH-79: There is no FORTH-79 equivalent for */ . 

Definition: : */ ( multiplier\multiolicand\divisor -- quotient ) 

♦/MOD SWAP DROP ; 


DOCOL 


♦/MOD 


SWAP 


DROP 


;s 



Perform the multi¬ 
plication, then the 
division, and leave a 
remainder and quotient. 


Set up for DROP . Bring 
the remainder to the 
top of the stack. 


Drop the remainder, 
leaving only the 
quotient. 
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*/MOD 


♦/MOD ( multiplicand \ multiplier \ divisor — remainder \ quotient) 

♦/MOD (pronounced "times-divide-mod") performs a multiplication and then a division of three 16-bit signed single precision values 
according to the algebraic statement (valuel * value2) / value3. 

Both a 16-bit signed single precision quotient and a 16-bit signed singie precision remainder (hence the "MOD” in the name) are the 
output of this operation. 

Logically */MOD is the same as the sequence: 


valuel value2 * value3 / 


but */MOD carries the result of the multiplication as a 32-bit signed double precision intermediate result. This allows greater accuracy 
than if a single precision intermediate product was used. 

*/MGD is srithmsticsliy idsnticsi to */ sxcspt */ droos ths rsrnsindsr* 

♦ At entry - The parameter stack contains three 16-bit signed single precision values. The second and third stack entries 
are to be multiplied together with the resulting product divided by the 16-bit signed single precision value on the top of 
the parameter stack. 

* At exit - The top of the parameter stack contains the 16-bit signed single precision quotient. The second stack entry 
contains a 16-bit signed single precision remainder. 

♦/MOD is a high level colon definition. 

Refer to ♦/ . 


FORTH-79: The FORTH-79 equivalent for */MOD is ♦/MOD . 

Definition: : VMOD ( multiplicand\ multiplier\division -- remainder\ quotient) 

>R M* R> M/ ; 


DOCOL 


>R 


M* 


R> 


M / 


;S 



Set up for M* . 
Temporarily save the 
divisor on the return 
stack. 


Perform the (valuel * 
value2) portion of the 
operation. 


Set up for M/ . 
Retrieve the divisor 
from the return stack. 


Perform the division 
leaving a remainder and 
a quotient. 
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+ 


+ ( valuel \ value2 — value ) 

+ (pronounced "plus") adds the top two 16-bit signed numbers on the parameter stack and replaces them with their 16-bit signed sum. 
Note that generation of a carry goes unnoticed. 

* At entry - The top and second entries of the parameter stack contain the signed 16-bit single precision values to be 
added. 

* At exit - The top of the parameter stack contains the signed 16-bit single precision sum of the two values. 

+ is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for + is + . 



HPUSH Push sum back onto top 

of parameter stack. 

NEXT 
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+ ! 


+! ( value \ address — ) 

(pronounced "plus-store") adds the 16-bit value contained in the second parameter stack entry to the 16-bit memory word addressed via 
the entry on the top of the stack. 

This is a commonly used method of incrementing counters kept in memory. 


HOLD is an example of a word that uses +'. . 


* 


At entry - The top of the parameter stack contains the address 
The second stack entry contains the signed 16-bit single precision 


of a 16-bit memory word to be used as an accumulator, 
value to be added to the word in memory. 


* At exit - No parameters. The word in memory contains the sum of its previous contents and the specified value. 


+1 is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent of +'. is +1 . 
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NEXT 
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+ 


+- ( value to have sign set \ value whose sign is used — value whose sign is set ) 

+- (pronounced "plus-minus") negates the sign of the second stack value if the sign of the top stack value is negative. The top value is 
then dropped. 

The following truth table describes the outcome of all possible combinations: 


Second 

Top of 


Entry 

Stack 

Results 

+ V2 

+ VI 

+ V2 

+ V2 

- VI 

- V2 

- V2 

+ VI 

- V2 

- V2 

- VI 

+ V2 


ABS is an example of a word that uses +- . 

* At entry - The top of the parameter stack contains a signed 16-bit single precision value. The second stack entry contains 
the 16-bit signed single precision value which is to have its sign bit set. 

* At exit - The top of the parameter stack contains the value originally in the second stack entry. The sign of this 16-bit 
signed value is set according to the truth table. The original top of stack value is dropped. 

+- is a high level colon definition. 

Refer to ABS , and D+- . 

FORTH-79: There is no FORTH-79 equivalent for +- . 


Definition: 


DOCOL 


(X 


IF 


( value\ signed value -- signed value ) 
0< IF MINUS THEN ; 



Set the "second" stack 
value to minus. 


Entry point from "false 
branch" of previous IF 
structure. 
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+ BUF 


+8UF ( buffer address — next buffer address \ flag ) 


+BUF (pronounced "plus-buff") advances the specified buffer address to the address of the next buffer. 
The action of +BUF is directly related to the physical arrangement of the buffers in a FORTH system. 


A system normally contains several buffers. (Refer to Figure +BUF-1.) Each buffer consists of a one word header, a data portion, and a 
terminator word. The header contains the block numoer ana an -upaate flag m the hiyn uiuci uu. \=.<=e xe.. y ... jib 

body is specified by the constant B/BUF . The terminator word consists of nulls and is used to flag the interpreter that the end of the 

block has been reached. 


These buffers are located in memory as a physically contiguous buffer array. While the buffers are physically contiguous, they are 
logically treated as a "circular" array. A reference to +BUF always returns the address of the next buffer in the circular array. 

* At entry - The top of the parameter stack contains the 16-bit address of the beginning of a buffer. 

* At exit - The top of the parameter stack contains a boolean flag which is false (0) if the returned buffer address equals 

n_«. _ a oDn/ TKp -fion 4-f'np font n^ if fhp rpfiimprl address does not eaual that in PREV . (This flag is primarily 

used by BLOCK to determine when aii buffers have been scanned for the desired block number./ .he second stack entry 
contains the 16-bit address of the next buffer in the "logically circular" buffer array. 


+BUF is a high level colon definition. 

Refer to BLOCK , PREV , UPDATE , and BUFFER . 


FORTH-79: There is no FORTH-79 equivalent for +BUF . 

Definition: : +BUF ( buffer address — next buffer address\flag ) 

B/BUF 4 + + DUP LIMIT = IF DROP FIRST 

DUP PREV (a) - ; 


THEN 




Update bit 


n 


Address 
contained 
within 
FIRST . 






Block number 


r- 

rea 

:r i 

data s 

BUFFE 


0000 



BUFFER 2 

1- 

0000 




LOW MEMORY 


the Block 


^Terminator Flag 


(Number of buffers isl 
[system dependent. T 


+BUF causes 
buffers to 
be scanned 
as if they 
were a 
circular 
string. 



HIGH MEMORY 


Address contained 
within LIMIT . 


DQCOL 


B/BUF 


LIT 

04 


+ 


+ 


DUP 



8080 fig-FORTH 
Version 1.1 


Set up for + . B/BUF 
specifies the length of 
the data portion of a 
buffer. 


Set up for + . 4 must 
be added to the buffer 
length because of the 
buffer's 2-byte block 
number header and the 2 
bytes of zeroes for a 
terminator. 

Compute the length of 
one buffer. 


Aim at the next 
buffer. 


Set up for = . 
Duplicate the new 
buffer address so it 
can be compared with 


LIMIT . 


Figure +BUF-1 
FORTH Buffer Structure 
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LIMIT 


F 


DROP 


FIRST 


THEN 



DUP 


PREV 


© 




Place the constant 
value LIMIT (the 
first memory 
location past the 
end of the buffer 
array) onto the top 
of the parameter 
stack. 



Replace the top two 
values on the 
parameter stack with 
a true flag (1) if 
they are equal or a 
false flag (0) if 
they are not equal. 




Set up for = . If the 
new buffer address 
equals this address, 
the buffer "limit" has 
been reached. 


Determine if the new 
buffer address has been 
incremented past the 
end of the buffers. 


Test if have 
I incremented past the 
physical end of the 
buffers. 



^»(pBUFl) 


Branch around "true 
portion" if the LIMIT 
has been reached. 


Drop the top value 
from the parameter 
stack. 


Drop the newly 
calculated buffer 
address since it points 
past the end of the 
buffers. 


Place the constant 
value FIRST (the 
beginning address of 
the first buffer in 
the buffer array) 
onto the top of the 
parameter stack. 


Loop back to the 
beginning of the 
buffers. This operation 
is what makes the 
contiguous buffers into 
a "logically circular 
string of buffers". 


This is the entry point 
from the "false branch" 
of the previous IF . 



Set up for - . 
Duplicate the buffer 
address so it can be 
compared with that in 
PREV . 


Set up for (a) . PREV 
contains the address of 
the most recently 
accessed buffer. 


Set up for - . Pick uy 
the buffer address 
currently in PREV . 


;S 


Subtract th 
stack entry 
second stac 
and replace 
values with 
signed diffe 

e top 
from the 
< entry 
the two 
their 

rence. 



(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


Compare the new buffer 
address with the most 
recently accessed 
buffer address. Leave a 
false flag (0) if they 
are equal and a true 
flag (not 0) if they 
are not. This flag is 
primarily used by 
BLOCK to determine 
when all buffers have 
been scanned for the 
desired block number. 
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+ LOOP 


+LOOP 


COMPILE TIME: ( loop address \ security check value — ) 

(Sequence 2) 

EXECUTION TIME: ( increment value — ) 

(Sequence 3) 

+LOOP (pronounced "plus-loop") is a compiler word and therefore exhibits two different sets of actions; those actions at compile time 
and those at execution time. 


+LOOP is used to end a DO-LOOP structure in conjunction with the word DO . 

+LOOP may only be used within a colon-definition. Since +LOOP must be paired with a DO DO leaves a 3 on the stack at compile time 
(Sequence 2) and +LOOP checks for this value. Since no other conditional or looping words leave a 3 on the stack, failure to pair +LUCJP 
with, a DO will cause an error condition to be signalled by 7PAIRS . 

The apparent run time action (Sequence 3) of +LOOP is to increment the loop Index by the specified value and compare it with the Limit 
value. This _ action is actually performed by (+LOOP) . If the increment value is positive, a branch back to the loop body of the loop 
structure is executed if the Index is either larger than or equal to the Limit. If the increment value is negative, a branch back t 
"loop body" is executed if the Index is larger than the Limit. If a "loop" back is not executed, the Index and Limit are dropped from the 
return stack and execution continues with the definition following +LOOP . 

Note that +LOOP is an IMMEDIATE word. This means that its precedence bit is set, and it will therefore execute at compile time. 


COMPILE TIME (Sequence 2): 

* At entry - The top of the parameter stack contains a 16-bit single precision value used to provide compiler security. The 
value 3 is left on the stack at compile time by DO . The second stack entry contains a 16-bit address specifying the entry 
point of the DO portion (i.e., the beginning of the "loop body") of the DO-LOOP structure. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - (+LOOP) expects the top of the parameter stack to contain a 16-bit signed single precision increment value 
which is added to the Index value. The Index and Limit values are expected to be on the return stack. Refer to 
(+LOOP) . 

* At exit - (+LOOP) drops the increment value from the parameter stack each time it is executed. It also drops the Index 
and Limit values from the return stack when the DO-LOOP structure is exited. 

LIKELY ERROR MESSAGES: 

COMPILATION ONLY (11H) — This word may only be used within a colon definition. 

CONDITIONALS NOT PAIRED (13H) — There is some sort of problem with the pairing of conditionals within the definition being 

compiled. 

+LOOP is a high level colon definition. 

Refer to (+LOOP) , DO , LOOP , and (DO) . 

FORTH-79: The FORTH-79 equivalent for +LOOP is +LOOP . 

Definition: : +LOOP ( loop address\security check value-) ( compile time parameters ) 

3 ?PAIRS COMPILE (+LOOP) BACK ; IMMEDIATE 
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COMPILE TIME action of +LOOP (Sequence 2): ( loop address\ security check value — ) 


DOCOL 


3 


7PAIRS 


COMPILE 



A +LOOP with a 
corresponding DO will 
result in a 3 on the 
stack, so check for it. 


Set up for 7PAIRS . 


Issue Error Message 13H 
(CONDITIONALS NOT 
PAIRED) if top two 
values not equal. 

NOTE: If an error 
message is issued, a 
QUIT will also occur 
and execution will stop 
here. _ 


This puts (+LOOP) into 
the definition being 
compiled. 


(+LOOP) 


BACK 


;S 


IMMEDIATE 



(+LOOP) is compiled 
into the definition. 


The address left by DO 
is used to calculate a 
return branch offset. 
This offset is then 
compiled into the 
definition and 
referenced by (+LOOP) 
at execution time. 


+LOOP is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


EXECUTION TIME action of +LOOP (Sequence 3): ( increment value — ) 
Refer to (+LOOP) for the RUN TIME action of +LOOP . 
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+ ORIGIN 


+ORIGIN 

COMPILE TIME (Sequence 2): ( - ) 

EXECUTION TIME (Sequence 3): ( offset — address ) 

+ORIGIN (pronounced "plus-origin") is a compiler word and therefore exhibits two different sets of actions; those actions at compile time 
and those at execution time. 

♦ORIGIN is used to obtain the address of a particular start-up parameter located within the "origin parameters". 

The "ORIGIN" is a location in the FORTH system that marks the beginning of a series of parameters primarily used to initialize the 
system (see COLD ). 

The following list of parameters, taken from the 8080 fig-FORTH Version 1.1 listing, are used to initialize the user variables: 

OFFSET PARAMETER DESCRIPTION 

0 SO Initial parameter stack pointer address. 

2 R0 Initial return stack pointer address. 

4 TIB Terminal Input Buffer address. 

6 WIDTH The number of characters saved in a Name Field. 

8 WARNING The flag denoting error message status. 

10 FENCE The address below which the dictionary cannot be forgotten. 

12 DP The next available dictionary location. 

14 VGC-LINK The pointer to the last chronologically added vocabulary (FORTH at start up). 

By supplying +GRIGIN with a byte offset (or word offset on word addressable machines), the address of a specific parameter can be 
obtained. 

COMPILE TIME (Sequence 2): 

* At entry - No parameters. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - The top of the parameter stack contains a signed (best to be positive though) single precision offset value. 

* At exit - The top of the parameter stack contains the 16-bit address of the specified origin parameter. 

♦ORIGIN is a high level colon definition. 

Refer to COLD and the user variables SO , R0 , TIB , WIDTH , WARNING , FENCE , DP , and VOC-LINK . 

FORTH-79: There is no FORTH-79 equivalent for +ORIGIN . 

Definition: : +ORIGIN ( offset -- address ) ( execution time ) 

ORIGIN + ; 
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COMPILE TIME action of +ORIGDM (Sequence 2): ( — ) 


This compile time action of +ORIGIN 
compilation time. 


is shown because of the odd 


way the FORTH fig-Model provides the origin area address at 


0 


DOCOL 


LITERAL 


+ 


;s 



Place the ORIGIN 
parameter area address 
(0 in this example) 
onto the top of the 
parameter stack while 
compiling . 


Compile the ORIGIN 
address into the 
dictionary. 


When +ORIGIN is 
executed, add the value 
on the top of the 
parameter stack to the 
origin address. 


EXECUTION TIME action of +ORIGIN (Sequence 3): ( offset — address ) 


DOCOL 


LIT 

ORIGIN 


+ 



Get the beginning 
address of the Origin 
Parameter Area. 


Add the offset to the 
beginning address to 
give the address of the 
desired parameter. 


;s 


(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 
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3 


, ( value — ) 

(pronounced "comma") compiles (i.e., stores) the 16-bit value on the top of the parameter stack into the next available dictionary 
location and advances the dictionary pointer. 

- ... •• ■ -n • _ •_ u • : _ 1 _ x fka /4infinn<9m> f e=k r-% TMTP"D OP? P"T i icoc tn nnmnilo 

, is Che primary compiler wora. mis is me principle mecms ui uumpinny a wui^ mtu u 10 uiuuu . 7 *- 

definitions into the dictionary). 

* At entry - The top of the parameter stack contains the value to be stored into the dictionary. 

* At exit - No parameters. 

, is a high level colon definition. 

Refer to INTERPRET . 

rGRTH-79; The FORTH-79 equivalent for , is , . 

Definition: : 1 ( value — ) 


HERE ! 2 ALLOT 


DOCOL (Run time portion of 

:). Save IP and 
start interpreting 
this definition. 


Put address of next 
available dictionary 
location onto top of 
parameter stack. 


Set up for 1 


Store the specified 
value into the 
specified memory 
location. 


"Compile" the value 
into the dictionary. 


Put the constant 2 
onto the top of the 
parameter stack. 


Allot 2 bytes for the 
8080 fig-FORTH Version 
1 . 1 . 


ALLOT 


Allot two memory 


Aim Dictionary Pointer 
(DP) past the word just 
stored. _ 


(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 
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( minuend \si3trahend — difference ) 

- (pronounced "subtract" or "minus" in FORTH-79) is a signed single precision subtraction that subtracts the entry on the top of the stack 

from the second stack entry and replaces both values with their difference. 

The high level subtraction is performed by two's complementing the subtrahend and then adding the two values together. 

* At entry - The top of the parameter stack contains a signed 16-bit single precision value which is the subtrahend in the 
subtraction. The second stack entry contains a signed 16-bit single precision value which is the minuend in the 
subtraction. 

* At exit - The top of the parameter stack contains the signed 16-bit single precision difference between the two input 
values. 

- is a high level colon definition. 

Refer to MINUS . 


FORTH-79: The FORTH-79 equivalent for - is - . 


Definition: : - ( minuend\ subtrahend--difference ) 

MINUS + ; 


DOCOL 


MINUS 


+ 


;S 



Set up for + . Set up 
for two's complement 
"subtraction". 


Adding the two's 
complement of the 
subtrahend to the 
minuend is the same as 
subtracting an 
uncomplemented 
subtrahend from the 
minuend. 


38 







-> (-) 


> 

—> (pronounced "next-block") is used at the end of a text screen in place of ;S to force interpretation to continue on tc the next 

sequential screen. 

Note: It is not "legal" to continue a colon definition onto the next screen (i.e., a ; must terminate a definition before a —> is issued). 

As a matter of programming style, it is often desirable to create a "load screen" which specifically loads each screen via LOAD (with 
each LOAD followed by a comment describing the screen to be loaded) rather than loading multiple screens via —> . This makes it much 
sssisr to kssp trsck of whst is hsinQ losdod* 

—> is an IMMEDIATE word since its purpose is to increment to the next screen during compilation. This means that its precedence bit is 
set and it will therefore execute at compile time. 

* At entry - No parameters. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

USE ONLY WHEN LOADING (16H) — This word should only be used when loading. 


--> is a high level colon definition. 


Refer to LOAD , and INTERPRET . 


FORTH-79: ~> is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". 


Definition: 


DOCOL 


7LOADING 


0 


IN 


B/SCR 


BLK 


7LOADING 0 IN '. B/SCR BLK (a) 
IMMEDIATE 



Make sure the contents 
of BLK is not 0 (i.e., 
input coming from 
disk). 


Set up for '. . 


Set up to reset IN to 
0 . 


Initialize IN to 0 so 
interpretation will 
begin at the first 
character of the block. 


By convention a screen 
is 1024 bytes long. The 
number of physical disk 
blocks (or sectors) 
composing a screen 
varies with each 
system. 


Set up for MOD . BLK 
contains the block 
number currently being 
interpreted. A zero 
denotes terminal input. 


OVER MOD - BLK +1 


© 


OVER 


MOD 



Set up for MOD . Pick 
up the block number 
currently being 
interpreted. 



Get the remainder of 
the current block 
number divided by 
blocks per screen. This 
is the relative block 
number from the 
beginning of the 
current screen. 


Set up for +'. . Sub¬ 
tract this remainder 
from B/SCR . The 
difference is the 
number of blocks to the 
beginning of the next 
screen. 

NOTE: The previous 
B/SCR BLK @ OVER 
MOD - sequence is 
necessary because there 
may be more than one 
physical block per 
screen. Since the --> 
may occur any where on 
the screen, a simple 
increment to the next 
physical block will not 
suffice. The beginning 
block number of the 
next sequential screen 
must be computed. 
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BLK 


+: 


;S 


IMMEDIATE 



Set up for +'. . Aim at 
BLK so it can be 
incremented. 


Aim BLK at the 
beginning of the next 
screen. 


--> is a compiler word 
and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
the next screen. 
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DUP 


-DUP 

If zero: ( valuel — valuel) 

If non-zero: ( valuel — valuel \ valuel) 

-DUP (pronounced "dash-dupe") duplicates the top of the parameter stack if its value is non-zero. For example: 

0 -DUP will result in 0 being left on the stack. 

102 -DUP will result in 102 102 on the stack. 

* At entry - The top of the parameter stack contains a value to be duplicated. 

* At exit - The value is duplicated if it is non-zero. In either case, the original value is on the top of the stack. 
-DUP is a high level colon definition. 

Refer to IF . 

FORTH-79: The FORTH-79 equivalent for -DUP is ?DUP ("query-dupe"). 

Definition: : -DUP ( valuel — value 1 or value l\ valuel ) 

DUP F DUP THEN ; 
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-FIND 

-FIND 

Successful: ( — PFA\ length \ true flag ) 

Unsuccessful: ( — false flag ) 

-FIND (pronounced "dash-find") reads a word from the input stream and then searches the CONTEXT and CURRENT vocabularies for a 
definition whose name matches the input word. 

The basis for -FIND is (FIND) . 

* At entry - The next text word in the input stream (delimited by blanks) is used as the character string to search for. The 
parameter stack contains no input parameters. 

* At successful exit - The top of the parameter stack contains a true flag (1). The second entry contains the matching 
definition's length byte. The third entry contains the matching definition's Parameter Field Address (PFA). 

* At unsuccessful exit - The top of the parameter stack contains a false flag (0). 

LIKELY ERROR MESSAGES: 

? pronounced "HUH?" (0) — The word in question cannot be found in the dictionary. 


-FIND is a high level colon definition. 

Refer to (FIND) , and WORD . 

FORTH 79: The closest FORTH-79 equivalent to -FIND is FIND 


Definition: 


-FIND ( — PFA\ length\ true flag ) 

( -- false flag ) 


DOCOL 


BL 


WORD 


HERE 


CONTEXT 


(-find) 




(Run time portion of 
:) Save IP and 
start interpreting 
this definition. 


Place the constant 
value (20H) for an 
ascii blank onto the 
top of the parameter 
stack. 


Input the next 
"word" from the text 
stream and place the 
character string at 
HERE . 


Set up delimiter value 
for WORD . 


This moves the 
character string being 
searched for to HERE 


(FIND) 


Place the address of 
the next available 
dictionary location 
onto the top of the 
parameter stack. 

Set up for (FIND) by 
placing the address of 
the text string being 
searched for onto the 
stack. 


I 


Place the address of 
the user variable 
CONTEXT onto the 
top of the parameter 
stack. 

CONTEXT contains an 
indirect pointer to the 
top of the CONTEXT 
vocabulary. 




Replace the 16-bit 
address on the top 
of the parameter 
stack with the 

16-bit contents of 
that memory 
location. 

Aim at a location 
inside the CONTEXT 
VOCABULARY 
definition which points 
to the top definition in 
that vocabulary. 


DUP 


0 = 



Aim at the top of the 
CONTEXT vocabulary. 
Set up for (FIND) . 


Search the CONTEXT 
vocabulary first. 


Duplicate the truth 
flag left by (FIND) . 

1 = Found 

0 = Not Found 
(The flag is duplicated 
so that a copy of it 
will remain after 
execution of the 
following IF 
statement.) 


Set up for IF . The 
"true portion" of the IF 
statement will be 
executed if no match 
was found in the 
CONTEXT vocabulary. 
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-TRAILING 

-TRAILING ( beginning addr\ count — beginning addr\ count) 

-TRAILING (pronounced "dash-trailing") supresses trailing blanks when outputting a character string with TYPE . The input parameters 
for -TRAILING are identical to those for TYPE (as set up by COUNT ). Using these parameters, -TRAILING examines the character 
string and reduces the character count so that trailing blanks are not output by a subsequent TYPE . -TRAILING scans backwards from 
the last character towards the first character. The first non-blank character encountered stops the scan. 

.LINE is an example of a word which uses -TRAILING . 


* At entry - The top of the parameter stack contains the character count of the text string including any trailing blanks. 
The second entry contains the true beginning address of the text string (i.e., the first character after the count byte). 

* At exit - The top of the parameter stack contains the adjusted character count of the text string excluding any trailing 
blanks. The second entry contains the beginning address of the text string. 


-TRAILING is a high level colon definition. 

Refer to COUNT , and TYPE . 

FORTH-79: The FORTH-79 equivalent for -TRAILING is -TRAILING . 


Definition: : -TRAILING ( beginning addr\ count -- beginning addr\ count) 

DUP 0 DO 

OVER OVER + 1 - C® BL - 

F LEAVE 
ELSE 1 - 
THEN 
LOOP ; 


OVER 



OVER 


C(§ 


BL 


Copy the second 
parameter stack 
value onto the top 
of the parameter 
stack. 


Set up for + 
address. 


Copy the 



Set up for + . Copy the 
count. 


Calculate the address. 


Set up to subtract 1 
from the address, 
(i.e., True beginning 
address plus count 
equals one byte past 
the end of the string.) 


Calculate the address 
of the character to 
examine. 


Pick up character to 
examine. 


Set up for comparison 
( - ). Will compare 
character with "blank". 


Is the character a 
blank? Set truth flag 
to non-zero if not. 
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IF 


LEAVE 



Force exit from loop 
by setting loop 
Limit scjusl to 
current Index. 


Branch. 


Character is a blank, 
so branch around "true 
portion" of IF 
statement. 


Character was not a 
blank. 


Exit loop leaving 
address of first 
non-blank character on 
stack. 


»(pTRA3) 


Branch around "false 
portion" of IF 
statement, (i.e., The 
character is not a 
blank). 


ELSE 


.(dtraJ) 


(LOOP) 


LOOP 


— 

_ 


Place the constant 
value 1 onto the top 
of the parameter 
stack. 




Subtract the top 
stack entry from the 
second stack entry 
and replace the two 
values with their 
signed difference. 





Increment the Index 
value. 




Entry point for "false 
portion" of previous IF 
statement, (i.e., The 
character was a blank.) 


Character was a blank. 
Set up to decrement 
count by 1. (i.e., To 
truncate a trailing 
blank.) 


Decrement the string 
count by 1. 


Fnfrw nninf fnr fho 

-v* w. .w 

physical end of the 
previous IF statement. 


This execution time 
portion of LOOP is 
compiled into the 
definition by LOOP . 



^■(pTRAl) 


Loop back to the DO if 
Index does not equal 
Limit and continue 
decrementing until 
encountering a 
non-blank character. 


If Index is = or > than 
Limit, do not loop. 
Drop the Index and 
Limit values from the 
return stack. 


;s 


(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 










. ( value to be output — ) 

. (pronounced "dot") performs a binary-to-ascii conversion (pictured numeric output) on the 16-bit signed value on the top of the stack 
and prints the result (followed by one space) on the output device. The sign is printed only if the value is negative. The current value in 
BASE is used as the conversion radix. 

NOTE: Since this is a signed conversion, problems arise when attempting to display 16-bit addresses which have their high order (sign) bit 
set. The set bit is interpreted as a negative bit and the value is displayed as a 15-bit negative number. This can be avoided by using U. 
which puts a zero onto the stack on top of the original value thereby making it a positive double precision value and then uses D. to print 
the result. 

The basis of . is D. . (The pictured numeric words; <# , #S , SIGN , and #> ; are used to actually convert the value. These are located in 
D.R ). 

* At entry - The top of the parameter stack contains a signed 16-bit value to be converted and printed. 

* At exit - No parameters. 

. is a high level colon definition. 

Refer to D. , and D.R . 

FORTH-79: The FORTH-79 equivalent for . is . . 

Definition: : . ( value --) 

S -> D D . ; 
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JJ 


( -) ■ 

(pronounced "dot-quote") is a special FORTH word that exhibits both execution and compile time traits. The purpose of the word is to 
output a text string. When this string is output depends upon the state of the system when the word is executed. V/hen execution begins, 
a test is made to determine if the system is in execution or compile state. 

." is used in the form: 


." text string " 


where the terminating delimiter is a " (quote). 

If the system is in execution state (i.e., ." is not inside of a definition), the text string is output immediately. If the system is in compile 
state, ." behaves as a standard compiler word and therefore exhibits two separate types of behavior: compile time and execution time 
behavior. 

At compile time - the execution-time procedure address (that of (.")), the length of the string, and the string itself are compiled into the 
Parameter Field of the definition. (Refer to (.") for a description of what this definition looks like in the dictionary.) 


At execution time - the procedure (.") outputs the text string. 

The maximum allowable string length is installation dependent. 

* At entry - ." must be followed by the character string to be output and delimited by " (quote). 

* At exit - No parameters. 

." is a high level colon definition. 

." is defined as IMMEDIATE and therefore has its precedence bit set causing it to execute during compilation. 
Refer to (.") . 

FORTH-79: The FORTH-79 equivalent for ." is ." . 

Definition: :."(—) 

22 STATE fa) IF COMPILE (.") WORD HERE C(a) 1+ ALLOT 
ELSE WORD HERE COUNT TYPE 
THEN ; IMMEDIATE 


DOCOL 


LIT 

22H 


STATE 


© 


F 



COMPILE 


(.") 


WORD 



NOTE: The system is in 
compilation state so 
compile the text string 
into the definition. 


This COMPILE executes 
when ." is being used 
within a definition 
(i.e., at Sequence 2). 


(.") is put into the 
definition by the 
previous COMPILE . 
NOTE: Before 
completion of execution, 
(.") will increment the 
inner interpreter pointer 
(IP) past the following 
text string (at 
Sequence 3). 


NOTE: WORD reads the 
text string into the 
dictionary but does not 
advance the dictionary 
pointer ( DP ). 


47 











HERE 


C(§ 


1 + 


ALLOT 


ELSE 



WORD 


HERE 


COUNT 


TYPE 


Put the address of 
the next available 
dictionary location 
onto the top of the 
parameter stack. 



The top of the stack 
will be aiming at the 
length byte. 


Get string length in 
preparation for 
ALLOTting the 
dictionary space 
occupied by the text 
string. 


Include the length byte 
in the amount of 
memory to be 
ALLOTted. 


i.e., Allocate the 
memory space already 
occupied by the text 
string. 



Branch around "false 
portion" of previous 
IF . 


THEN 



. \ DOTQ21- 

- 


5^ 

(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


IMMEDIATE 


Set the precedence 
bit of this 
definition so it 
will be executed at 
compile time and not 
compiled into the 
definition. 



Entry point for "false 
portion" of previous IF 
statement which tested 
that the system was in 
execution state. 

NOTE: The system is 
in execution state so ^ 
output the text string j 
immediately. 


The top of the stack 
will be aiming at the 
length byte. Set up for 
COUNT. 


Set up for TYPE . 


Using the parameters 
supplied by COUNT . 


Entry point from branch 
around "false portion" 
of previous IF 
statement. 


." is a compiler word 
and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 
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LINE 


.LINE (line # \ screen # — ) 

.LINE (pronounced "dot-line") prints a line of text from a screen stored on disk. Trailing blanks are suppressed and not printed. 

The basis of .LINE is (LINE) . The constant C/L specifies the line length. 

* At entry - The top of the parameter stack contains a signed 16-bit single precision value which is the desired screen 
number and the second entry contains a signed 16-bit single precision value which is the desired line number. 

* At exit - No parameters. 

.LINE is a high level colon definition. 

Refer to (LINE) . 

non Thsrs is no FQRTH-79 scjuivslsnt for -LINE - 

Definition: : .LINE ( line #\screen # — ) 

l (LINE) -TRAILING TYPE ; 


DOCOL 


(LINE) 


-TRAILING 


TYPE 


;S 
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.R 


.R ( value \ field width — ) 

.R (pronounced "dot-R) performs a binary-to-ascii conversion (pictured numeric output) on the signed 16-bit value in the second stack 
entry and prints the result right justified in a field whose minimum width is specified by the value on the top of the stack. For example, 
if a field width of 10 is specified and only 3 characters are printed, the remainder of the field will be left padded with 7 blanks (b). 

123 10 .R would result in B6B6BBB123 

Note, however, that the field width parameter specifies only a minimum field width. The entire value is always printed even if it 
exceeds the specified field width. No truncation occurs and no trailing blank is printed. 

The current value in BASE is used as the conversion radix. 

* At entry - The top of the parameter stack contains a signed 16-bit value which specified the field width of the converted 
ascii string. The second stack entry contains a signed 16-bit value to be converted and printed. 

* At exit - No parameters. 

.R is a high level colon definition. 

Refer to D.R . 

FORTH-79: .R is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". 

Definition: : .R ( value\ field width) 

>R S —> D R> D. R : 


DOCOL 


>R 


S->D 


R> 


D.R 


;S 



Temporarily save field 
width. 


Retrieve field width. 
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/ 


/ ( dividend \ divisor — quotient) 

/ (pronounced "divide") divides a 16-bit signed single precision value by another 16-bit signed single precision value and replaces them 
with their 16-bit signed quotient. The second stack value is divided by the top stack value. 


The basis of / is /MOD . /MOD leaves a quotient and remainder, 
which drops the quotient. 


T 'srTiindsr» j h ic 


very similsr to ? but opposite from MOO T 


* At entry - The top of the parameter stack contains a 16-bit signed single precision divisor. The second stack entry 
contains a 16-bit signed single precision dividend. 


* At exit - The top of the parameter stack contains the 16-bit signed single precision quotient. 


/ is a high level colon definition. 
Refer to /MOD . 


FORTH-79: The FORTH-79 equivalent for / is / . 

Definition: : / ( dividend's* divisor ~ quotient) 

/MOD SWAP DROP ; 


DOCOL 


/MOD 


SWAP 


DROP 


;s 



Leave the quotient on 
the top of the stack 
with the remainder 
under it. 


Set up for DROP . Get 
the remainder onto the 
top of the stack. 


L/i up ciio i O! i tail ivjgi ai ici 

leave the quotient. 
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/ MOD 


/MOD ( dividend \ divisor — remainder\ quotient) 

/MOD (pronounced "divide-mod") divides a 16-bit signed single precision value by another 16-bit signed single precision value and replaces 
them with a 16-bit signed quotient and a 16-bit signed remainder. The remainder takes its sign from the dividend. 

Note that /MOD uses a single precision dividend while M/ uses a double precision dividend. 

The basis of /MOD is M/ . The single precision dividend is converted to double precision and then an M/ is preformed. 

* At entry - The top of the parameter stack contains a 16-bit signed single precision divisior. The second stack entry 
contains a single precision 16-bit signed dividend. 

* At exit - The top of the parameter stack containsthe 16-bit signed quotient. The second stack entry contains the 16-bit 
signed remainder. 

/MOD is a high level colon definition. 

Refer to M/ . 

FORTH-79: The FORTH-79 equivalent for M/ is M/ . 

Definition: : /MOD ( dividend\ divisor--remainder\ quotient) 

>R S ~> D R> M/ ; 


DOCOL 


>R 


S->D 


R> 


M / 


;S 



Get the divisor out of 
the way. 


Convert the single 
precision dividend to 
double precision. 


Retrieve the divisor. 


Perform the division 
leaving the signed 
remainder and 
quotient. 
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0 


0 (- 0 ) 

0 is a single precision CONSTANT value. This value is used so often that it has been made into a CONSTANT. This was done to save 
compiling time. Before converting a character string into a numeric value, INTERPRET first searches both the CONTEXT and 
CURRENT vocabularies. A significant amount of time can be saved if a name match can be found during the dictionary search instead of 
searching both vocabularies and then converting the vaiue. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the signed 16-bit single precision value 0. 

FORTH-79: There is no FORTH-79 equivalent for 0 . 
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0< 


CK ( value — truth flag ) 

CK (pronounced "zero-less-than") examines a signed value on the top of the parameter stack and replaces it with a true flag (1) if the 
number is less than zero (negative) or with a false flag (0) if the number is greater than or equal to zero. 

SIGN is an example of a word that uses CK . 

* At entry - The top of the parameter stack contains the signed 16-bit single precision value to be examined. 

* At exit - The top of the parameter stack contains a truth flag. 

CK is a low level code primitive. 

Refer to SIGN . 

FORTH-79: The FORTH-79 equivalent for CK is CK . 



HPUSH Put truth flag onto top 

of parameter stack. 


NEXT 
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0 


0= ( value — truth flag ) 


0= (pronounced "zero-equal") examines the value at the top of the parameter stack and replaces it with a true flag (1) if the value is 
equal to 0 or with a false flag (0) if the value is not equal to 0. 


u~ is often used tu set up for an IF by compler 


anting the truth flag so the statement's "true portion" (as opposed to the "false" or ELSE 
portion^can perform "the desired function.' This makes for more readable FORTH . In this instance the word NOT should be used for 
clarity. NOT is defined as: 


: NOT 0= ; 


* At entry - The top of the parameter stack contains the signed 16-bit single precision value to be examined. 

* At exit - The top of the parameter stack contains a truth flag. 

0= is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for 0= is 0= . 



HPUSH Push truth flag onto 

top of parameter 
stack. 


NEXT 
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OBRANCH 


OBRANCH ( truth flag — ) 

This execution tine (Sequence 3) code (pronounced "zero-branch") is compiled into a definition (Sequence 2) by IF , UNTIL , and WHILE 
to perform a conditional branch. If the flag on the top of the parameter stack is 0 (false), the offset to which IP points at entry is added 
to IP to cause either a forward or backward branch depending upon the value of the offset (hence the name, OBRANCH ). If the flag is 
true, no branch is taken. Refer to BRANCH . 

* At entry - The top of the parameter stack contains a 16-bit boolean truth flag. 

* At exit - No parameters. 

OBRANCH is a low level code primitive. 

Refer to F , UNTIL , WHILE , and BRANCH . 

FORTH-79: There is no FORTH-79 equivalent for OBRANCH . 



NEXT 
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1 


1 (- 1 ) 


iiun UUINJ.H.N. vaiUC . This value is used so often that it has been made into a CONSTANT. This was done to save 
uumumuu Before converting a character string into a numeric value, INTERPRET first searches both the CONTEXT and 

CURRENT vocabularies. A significant amount of time can be saved if a name match can be found during the dictionary search instead of 
searchinn both vocabularies and then converting the value. 


1 is a single precision CONSTANT value 
compiling time 


* At entry - No parameters. 

* At exit - The top of the parameter stack contains the signed 16-bit single precision value 1. 
FORTH-79: There is no FORTH-79 equivalent for 1 . 
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1 + 


1+ ( value — value+1) 

1+ (pronounced "one-plus") adds 1 to the value on the top of the parameter stack. 

Note: The algebraic rules of signed addition apply here. 

* At entry - The top of the parameter stack contains a signed 16-bit single precision value. 

* At exit - The signed 16-bit single precision value on top of the parameter stack is incremented by 1. 
1+ is a high level colon definition. 

FORTH-79: The FORTH-79 equivalent for 1+ is 1+ . 

Definition: : 1+ ( value — value+1) 

i + ; 
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2 


2 (- 2 ) 

2 is a single precision CONSTANT value. This value is used so often that it has been made into a CONSTANT, This was done to save 
compiling time. Before converting a character string into a numeric value, INTERPRET first searches both the CONTEXT and 
CURRENT vocabularies. A significant amount of time can be saved if a name match can be found during the dictionary search instead of 
searching both vocabularies and then converting the value. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the signed 16-bit single precision value 2. 

FORTH-79: There is no FORTH-79 equivalent for 2 . 
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2 + 


2+ ( value — value+2 ) 

2+ (pronounced "two-plus") adds 2 to the 16-bit value on the top of the parameter stack. 
Note: The algebraic rules of signed addition apply here. 


TU« ~ £ »-U~ -~ _ 




* At exit - The value on top of the parameter stack is incremented by 2. 

2+ is a high level colon definition. 

FORTH-79: The FORTH-79 equivalent for 2+ is 2+ . 

Definition: : 2+ ( value — value+2) 

2 + ; 
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3 


3 (-3) 

3 is a single precision CONSTANT value. This value is used so often that it has been made into a CONSTANT. This was done to save 
compiling time. Before converting a character string into a numeric value, INTERPRET first searches both the CONTEXT and 
CURRENT vocabularies. A significant amount of time can be saved if a name match can be found during the dictionary search instead of 
searching both vocabularies and then converting the value. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the signed 16-bit single precision value 3. 

FORTH-79: There is no FORTH-79 equivalent for 3 . 


61 



COMPILE TIME: (-) 

(Sequence 2) 

EXECUTION TIME: (-) 

(Sequence 3) 

: (pronounced "colon") is the defining word used to create (i.e., define) a high level FORTH definition. It is used in the following format: 

: Specified name Body of definition ; 

: is a defining word and therefore exhibits two different sets of action; those actions at compile time and those at run time. 

The compile time (Sequence 2) action of : is: 

1. To create a definition header in the dictionary for the name specified 

2. To enter compile mode by setting the user variable STATE to a non-zero value (see STATE ). 

3. To set the CONTEXT vocabulary the same as the CURRENT vocabulary. 

A colon definition is terminated with either ; or ;CODE . 

The Code Address of the execution time portion of this word is compiled into the Code Field Address (CFA) of every colon definition 
word. 8080 Version 1.1 fig-FORTH references this routine via the label DOCOL . The purpose of this code is to save the current position 
of the Interpreter Pointer (IP) and begin execution of the body of this definition (i.e., thread "down" one level of threaded code). 

The execution time (Sequence 3) action of DOCOL can be symbolically described in high level terms as follows: 

IP (§ Fetch the contents of IP . ( IP points to the next CFA , i.e., "word" to execute.) 

RP (a) 1 Fetch the address of the top of the return stack and store the address of the "next word to execute" on it. 

-2 RP +1 Decrement the return stack pointer. 

W (a) Fetch the contents of W . ( W points to the Code Field of the definition being executed. DOCOL is the Code Field 
procedure that is executing.) 

2+ IP 1 Increment W to point to the Parameter Field entry following the Code Field and store this address into IP. The system 
has chained down one level of nesting and the Parameter Field of this new definition will now be executed. 

Note that : is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 

COMPILE TIME (Sequence 2): 

* At entry - No parameters. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At Entry - No parameters. 

* At Exit - No parameters. 

LIKELY ERROR MESSAGES: 

? pronounced "HUH?" (0) — The word in question cannot be found in the dictionary. 

EXECUTION ONLY (12H) -- This word must not be used while the system is in compile mode. 

DEFINITION NOT FINISHED (14H) — The position of the parameter stack pointer is not the same as it was when this definition started 
being compiled. Something is wrong with the definition. 

: is itself a high level colon definition. 

Refer to STATE , and VOCABULARY , 

FORTH-79: The FORTH-79 equivalent for : is : . 

Definition: : ( --) ( compile time) 

?EXEC 1CSP CURRENT (a) CONTEXT I CREATE ] (;CODE) 

Note: The (;CODE) is followed by assembly language sequence 3 time code. 

IMMEDIATE 
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COMPILE TIME action of : (Sequence 2): ( — ) 


DOCOL 


7EXEC 


'.CSP 


CURRENT 


(a) 


CONTEXT 


CREATE 



"Start" compilation. 
i.e., Set STATE to a 
non-zero value. 


(;CODE) 


IMMEDIATE 


Pop the address off 
the top of the 
return stack and 
place it into the 
Code Field of the 
word being defined. 
NOTE; A , is not 
necessary when 
(;CODE) is executed 
because the (;CODE) 
pops the top of the 
return stack and 
stores it and then 
executes a ; itself. 
This returns control 
to the procedure 
which, in this case, 
called s . _ 


Set the precedence 
bit of this 
definition so it 
will be executed at 
compile time and not 
compiled into the 
definition. 


i.e., Place the address 
of the run time code 
portion of : into the 
CF A of the word being 
defined. The top of the 
return stack in this 
case points to DOCOL , 
the run time code for : . 
This run time code 
immediately follows 
(;CODE) . 

Note (;CODE) is 
compiled into : by 
;CODE . 


: is a compiler word 
and therefore must 
execute during compil¬ 
ation (Seguence 2) so 
that it can compile 
other definitions. 











EXECUTION TIME action of : (Sequence 3): ( — ) 


NOTE: This code physically immediately follows the compile time (Sequence 2) code for : . 

This is a high level representation of the 8080 assembly language code in the 8080 fig-FORTH Version 1.1 listing. 



NEXT Go execute this 


definition. 
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9 

9 

COMPILE TIME : ( -) 

(Sequence 2) 

EXECUTION TIME: (-) 

(Sequence 3) 

. (pronounced "semicolon") is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and 
those at execution time. 

; is used to terminate a : ("colon") definition. 

The compile time (Sequence 2) action of ; is: 

1. To compile ;S (the execution time procedure of ;) into the definition being created. 

2. To SMUDGE the smudge bit, 

3. To place the system back into interpret mode (from compile mode) so that the next input data stream word can be interpreted. 

The execution action (Sequence 3) of ; is actually that of ;S . Basically ;S "chains back" up one level of nesting and "returns control" to 
the definition that "called" the definition now executing ;S . 

Note that ; is an IMMEDIATE word. This means that its precedence bit is set, and it will therefore execute at compile time. 

COMPILE TIME (Sequence 2): 

* At entry - No parameters. 

* At exit -No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - No parameters. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

COMPILATION ONLY (11H) — This word may only be used within a colon definition. 

DEFINITION NOT FINISHED (14H) — The position of the parameter stack pointer is not the same as it was when this definition started 
being compiled. Something is wrong with the definition. 

; is a high level colon definition. 

Refer to ;S , and : . 

FORTH-79: The FORTH-79 equivalent for : is : . 

Definition: : ; (--) 

| ?CSP COMPILE ;S SMUDGE [ 
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COMPILE TIME action of ; (Sequence 2): ( — ) 


EXECUTION TIME action of ; (Sequence 3): ( — ) 


DOCOL 


?CSP 


COMPILE 


;S 


SMUDGE 


( 


;s 


IMMEDIATE 



QUIT if the parameter 
stack has been left 
unbalanced by some act 
of compiling this 
definition. 


This compiles the 
execution time 
procedure ;S into the 
definition being 
compiled (at Sequence 
2 ). 


;S executes at Sequence 
3, not at compile time 
(Sequence 2). 


: would have originally 
smudged the bit. Now 
"unsmudge" it to make 
it a "findable" 
correctly compiled 
word. 


Stop compiling and set 
up the system so that 
it can interpret the 
next input data stream 
word. 


; is a compiler word 
and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


The execution time action of : is that of :S - 
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;CODE 


;CODE 

DEFINITION TIME: ( - ) 

(Sequence 1) 

EXECUTION TIME: ( - ) 

(Sequence 2) 

;CODE (pronounced "semicolon-code") is a defining word and therefore exhibits two different sets of actions; those actions at definition 
time and those at execution time. 

.rngr ; s 0 s e qu“no e 1 defining word that is used to create Sequence 2 defining words. ;CODE is used in conjunction with another 
defining word (one that creates the header of the defining word being created) to create defining words ("parents") that in tum create 
other words ("children"). 

When creating a defining word (at Sequence 1), ;CODE acts as a dividing line between the high level words that create the "child" (at 
Sequence 2) and the assembly language code words that are the "child's" run time procedure (at the "child's" Sequence 3). See Figure 
;CODE-l. 

The function of ;CODE is very similiar to that of DOES> except ;CODE defines the beginning of a code procedure while DOES> defines 
the beginning of a high level procedure. 

At Sequence 1 (i.e., when creating the "parent" defining word), ;CODE first compiles the address of its run time procedure, (;CODE) , 
(which actually executes at Sequence 2 when the "child" is created) and then stops compilation. 


Sequence 1 
A defining word 

;CODE 

Code level execution 
time procedure. 


The defining word 
is created. 

I 


which creates 


"PARENT" 
Sequence 2 


Name Field 


Link Field 


Code Field 


Compile time words 
;CODE 

Code level execution 
time procedure. 


The defining word 
is executed. 

i 

which creates 


"CHILD" 


Sequence 3 


Name Field 


Link Field 


Code Field 


Address of execution 
time code procedure. 


Parameter Field 


A definition is 
created via the 
defining word. 


Figure ;CODE-l 
Action of ;CODE 


At Sequence l (i.e., when compiling the "parent" defining word), the high level words which will create the "parent" during Sequence 2 
are compiled into the dictionary. ;CODE denotes the end of the "parent's" Sequence 2 compiling procedure and the beginning of the 
"child's" execution time procedure. Therefore, ;CODE must perform two main tasks: 

1. It must first compile (;CODE) into the definition. This execution time procedure for ;CODE actually executes at Sequence 2 
when the "parent" is creating the "child". Its function is to point the "child's" Code Field at the Sequence 3 code procedure that 
"lives" in the "parent" definition. 

2. ;CODE must then stop compilation. This is done because prior to ;CODE are high level definitions whose addresses are compiled 
into the dictionary, but after ;CODE are assembler directives which must execute in order to assemble op-codes into the 
dictionary. These assembler directives are not IMMEDIATE . Therefore, the system must be taken out of compile state so the 
interpreter will execute these directives. 

;CODE also SMUDGEs the header created by whatever defining word was used to begin the definition. 

Note that the Version 1.1 8080 fig-FORTH does not set CONTEXT to the ASSEMBLER vocabulary. To rectify this problem, the word 
ASSEMBLER should immediately follow ;CQDE . 

;CODE only executes at Sequence 1. (;CODE) executes at Sequence 2. (Refer to (;CODE) .) 

The end effect of ;CODE is that the dictionary definition structure of the "child" is determined by the words preceding ;CODE ; but, 
when the "child" executes at Sequence 3, the code following ;CODE is executed. 






This allows whole new families of dictionary structures and their associated run-time codes to process these structures to exist. An 
example of a structure could be a graphics control table while the code following ;CODE could display the table. 

Note that ;CODE is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 

DEFINITION TIME (Sequence 1): 

* At entry - No parameters. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 2): 

* At entry - No parameters. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

DEFINITION NOT FINISHED (14H) — The position of the parameter stack pointer is not the same as it was when this definition started 
being compiled. Something is wrong with the definition. 

;CODE is a high level colon definition. 

Refer to (;CODE) , DOES> , and <BUILDS . 

FORTH-79: There is no FORTH-79 equivalent for ;CODE . 

Definition: : ;CODE ( —) 

?CSP COMPILE (;CODE) [COMPILE] [ SMUDGE ; 

IMMEDIATE 


DEFINITION TIME action of ;CODE (Sequence 1): ( — ) 


DOCOL 


?CSP 


COMPILE 


(;CODE) 



Compile (;CODE) , the 
run time portion of 
;CODE , into the 
dictionary where it 
will be executed when 
the word being created 
is executed (Sequence 
3). 


This word is not 
executed while ;CODE is 
being compiled 
(Sequence i); but is 
executed when ;CODE is 
used to create a new 
definition (Sequence 
2 ). 


[COMPILE ] 


[ 


SMUuGt. 



Since [ is an 
IMMEDIATE word, 
[COMPILE ] must be 
used to compile it into 
the definition during 
Sequence 1. (Otherwise 
it would execute 
instead of being 
compiled.) [COMPILE] 
is only used to "compile" 
[ into ;CODE and does 
not exist in ;CODE's 
definition when ;CODE 
is executed at a later 
compile time (Sequence 
2 ). 


[ will be executed at a 
later compile time 
(Sequence 2). (The 
purpose of the [ in 
this later compile time 
is to stop Sequence 2 
compilation so that the 
assembler commands 
which follow can be 
executed to "compile" 
code into the 
dictionary.) 


This is executed at 
Sequence 2. It prevents 
the new definition from 
being "found" until the 
smudge bit is toggled 
with another SMUDGE 
upon successful 
completion of 
compilation. 
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;S (Run time portion of 

; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


IMMEDIATE 


Set the precedence 
bit of this 
definition so it 
will be executed at 
compile time and not 
compiled into the 
definition. 


;CODE is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


EXECUTION TIME action of ;CODE (Sequence 2): ( — ) 

The Sequence 2 action of ;CODE is to compile a (;CODE) into the definition being compiled. 


The execution time (Sequence 3) action of ;CODE is (;CODE) . 




;S 

;s (-) 

;S (pronounced "semicolon-S") is the execution time (Sequence 3) procedure compiled by ; . Its purpose, at the end of a colon definition, 
is to "chain back" to the next higher level by popping the return address of the calling procedure off of the return stack. 

;S is also used to stop interpretation of a screen. 

The action of ;S can be symbolically described in high level terms as follows: 

RP (a) Aim at the top of the return stack. (The top of the return stack contains the "return" address, i.e., The address of the 
next "word" to execute located within the Parameter Field of the definition which "called" the definition this ;S is in.) 

(a) IP '. Fetch the address of the next "word" to execute and store it into IP . 

2 RP +1 Increment the return stack pointer (i.e., free up this location). 

IP is all set to execute the next "word". The last thing ;S does is execute NEXT (which then executes the "next" word). 

* At entry - No parameters. 

* At exit - No parameters. 

;S is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for ;S is EXIT . 

Note: This is a high level representation of the 8080 assembly language code in the 8080 fig-FORTH Version 1.1 listing. 



NEXT 
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< 


< ( valuel\value2 — flag ) 


< (oronounced "less-than") performs a signed comparison of the top two single precision values on the parameter stack and replaces them 
Truth flag? The flag Is true (non-zero) if the second stack entry is less than the top stack entry (hence the name 
"iess-than"). Otherwise the flag is false (0) if the second stack entry is equal to or greater than the top entry. Note that this is just like 
an in-fix operation in which the operator has been moved outside. For example: 

S<4 (in-fix) is the same as 5 4< (post-fix) 


MAX is an example of a word which uses< . 

This is a signed comparison. 

* At entry - The top of the parameter stack contains a signed 16-bit single precision value to be compared with the second 
entry which is also a signed 16-bit single precision value. 

* At exit - The top of the parameter stack contains a true boolean flag (non-zero) if the second stack entry is less than the 
top of the stack or a false boolean flag (0) if it is greater. 

< is a high level colon definition. 

FORTH-79: The FORTH-79 equivalent for < is < . 

Definition: : < ( valuel\value2 — flag) 

0 < : 


DOCOL 


(K 


;s 



Determine if the second 
stack entry is smaller 
than the first. 


Set the truth flag to 
true (1) if the second 
entry is smaller than 
the first; else, ieave 
a false flag (0). 
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<# 

( — ) ( Refer to "At entry" section ) 


<# (pronounced "less-than-sharp") begins a double precision integer pictured numeric conversion expression. 


Pictured numeric conversion converts values on the stack into ascii strings which are formatted according to picture specifications, 
is similiar in concept to the BASIC PRINT USING or COBOL PICTURE statements. * 


This 


The character string is created in memory, starting one byte before PAD and working backwards toward low memory. The conversion 
takes place one digit at a time starting with the one's column, then the ten's column, etc. (That is why memory is filled in a right-to-left 
direction.) y 


The user variable HLD contains a pointer to the last converted character (see HOLD ). 
For example., the general structure of a pictured numeric expression is: 


<# 

# 

#S 

SIGN 

#> 

start 

one 

digit 

multiple 

digits 

sign 

end 


Some examples are: 

<// if // # #S #> gives at least 4 digits. 

<// it # 2EH HOLD #S #> gives 2-decimal places. 

The phrase <# #S SIGN S> is used by the word D.R . 

The description of # describes the binary-to-ascii conversion process in more detail. 

The specific purpose of <# is to initialize the pointer in HLD to aim at the beginning of PAD . (<# can be modified if it is desirable to 
create the string elsewhere; e.g., in the memory of a memory mapped CRT display, etc.). Once executed, <# should not be used again 
until a #> has been executed as this would cause converted characters to overlay previously converted characters in PAD . Also, no 
words should be executed during pictured conversion which would cause the end of the dictionary, hence PAD , to change location. 

NOTE: Although this word by itself reguires no parameters, correct FORTH coding technigues suggest that parameters not be introduced 
during the string conversion process. Therefore, pictured numeric conversion parameters should be set up prior to the execution of this 
word. 

* At entry - Although this word does not reguire any entry parameters, the top of the parameter stack should contain a 
31-bit value to be converted and output (see # ) with its high order portion in the first entry and the low order portion in 
the second entry. (Note the 31-bit value. # correctly converts only positive values. Therefore a DABS should normally 
precede the <// to convert negative double precision values to their absolute values.) If the output character string is to be 
signed, an optional 16-bit signed value may be located in the third stack entry. This parameter sets up for SIGN . (Refer 
to SIGN for a complete description of this parameter and how to set it up.) 

* At exit - This word by itself leaves no output parameters on the stack. Refer to #> for output of the pictured numeric 
conversion sequence. 

<# is a high level colon definition. 


Refer to // , #> , SIGN , HLD , and HOLD . 

FORTH-79: The FORTH-79 equivalent for <# is <# . 

Definition: : <# ( —) 

PAD HLD 1 ; 


DOCOL 


PAD 


HLD 



In 8080 fig-FORTH 
Version 1.1, PAD is 
located 68 bytes past 
the end of the 

dictionary. 

Set up for 1 . 


;S 



Initialize the pointer 
HLD with the beginning 
address of PAD . 
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< BUILDS 


<BUn_DS 

DEFINmON TIME: (-) 

(Sequence 1) 

EXECUTION TIME: ( - ) 

(Sequence 3) 

<BUILDS (pronounced "builds") is a defining word and therefore exhibits two different sets of actions; those actions at definition time and 
those at execution time. 

<BUILDS is a Sequence 1 defining word which is used to create Sequence 2 defining words. Words created by <BUILDS are then used to 
create other words. e.g., <BUILDS (Sequence 1) is used to create the defining word VOCABULARY (Sequence 2) which in turn creates 
vocabulary definitions such as FORTH , EDITOR , and ASSEMBLER . Such a word is then executed (Sequence 3) to set the point at which 

UlC LlUl iai j ocaiuico oi-aiu 

<BUILDS is normally used in conjunction with DOES> . When used this way, <BUILDS "builds" (hence the name) a dictionary header for 
the new definition. Refer to Figure <BUILDS-1. This header is actually the definition for the constant 0. Definitions between <BUILDS 
and DOES> are executed at compile time. 

The words between <BUILDS and DOES> are executed at Sequence 2 time while creating a new definition. The words following DOES> 
are executed at Sequence 3 time when executing the new definition. (Refer to Figure <BUILDS-1.) 

The compile time (Sequence 2) action of <BUILDS is to simply "build" a dictionary header for the new definition. This header is actually 
the definition for the constant 0. DOES> then overlays this header with execution time (Sequence 3) pointers for the word (refer to 
DOES>). The Code Field Address is overlayed to point to the execution time code for DOES> . The first entry in the Parameter Field 
(the 0) is overlayed with the address of the new definition's execution time (Sequence 3) definitions. This is the address of the first word 
following DOES> . 

The action of <BUILDS and DOES> can be more easily understood by observing how the words VOCABULARY and FORTH are created and 
used. VOCABULARY is created at Sequence 1 with <BUILDS and DOES> . The words following DOES> are compiled into the dictionary 
at Sequence 1 but will not be executed until Sequence 3 as explained later. Then, at Sequence 2, when VOCABULARY is executed to 
create a new definition (named FORTH in this example); the following happens: 

1. <BUILDS creates a constant 0 header, with the first Parameter Field entry filled in with the 0 value. (This ^important to note 
because this 0 will be overlayed by DOES> with the address of the execution time definitions for FORTH , which in turn means 
that the first Parameter Field entry in a <BUILDS-DOES> definition is not available for use.) 

2. The words following <BUILDS are also executed at Sequence 2 to build (compile) the vocablulary definition. 

3. The Pseudo Name Field is compiled into the definition. 

4. The Vocabulary Link Field is compiled into the definition. 

5. The Chronological Link Field is compiled into the definition. (<BUILDS has no Sequence 3 time action, i.e., When FORTH is 
executed.) 

6. After the Chronological Link Field is compiled, DOES> executes. Remember this is the compile time (Sequence 2) time action 
of DOES> . DOES> first overlays the Code Field of the definition being created, FORTH , with the Code Field Address of 
DOES>'s execution time (Sequence 3) code. 

The 0 in the first Parameter Field entry is overlayed with the address of the next dictionary location following DOES> . This is the 
address of the execution time procedure (Sequence 3) of the example word, FORTH. The words following DOES> were compiled at 
Sequence 1 into the VOCABULARY definition. 

Note this distinction: The execution time (Sequence 3) procedure for the example word, FORTH, (the definition created by 
VOCABULARY at Sequence 2); exists in VOCABULARY , not in FORTH. The first entry Parameter Field in FORTH points to this 
execution time procedure. 

When FORTH is executed at Sequence 3, its Code Field points to the execution time (Sequence 3) code for DOES> . The execution time 
purpose of DOES> is to transfer control to the execution time procedure (remember DOES> is for high level definitions) for the example, 
FORTH . It does this by fetching FORTH's execution time address from the first Parameter Field entry and placing it onto the return 
stack and calling NEXT . This code also causes the address of the second Parameter Field entry to be placed onto the top of the 
parameter stack. 

The execution time procedure for FORTH is then executed physically in the last half of VOCABULARY , then control returns to the word 
following FORTH. 


DEFINITION TIME (Sequence 1): 

* At entry - No parameters, 

* At exit - No parameters. 



EXECUTION TIME (Sequence 3): 

* At entry - No parameters, 

* At exit - No parameters. 
LIKELY ERROR MESSAGES: 


DICTIONARY FULL (2) — The dictionary has grown into the Terminal Input Buffer. 

DEFINITION NOT FINISHED (14H) — The position of the parameter stack pointer is not the same as it was when this definition started 
being compiled. Something is wrong with the definition. 

<BUILDS is a high level colon definition. 


Refer to DOES> , VOCABULARY , FORTH , and ;CODE . 

FORTH-79: The FORTH-79 equivalent for <BUILDS is CREATE . Refer to FORTH-79 Standard. 

Definition: : <BUILDS ( —) 

0 CONSTANT ; 


Sequence 1 


"PARENT" 
Sequence 2 


¥ 

CHILD" 

Sequence3 





Name Field 




Link Field 

<BUILDS 



Code Field 

<BUILDS 



Pointer to run time 
procedure 

DOES> 



Compiler words 

High level execution 
time procedure 



DOES> 




Execution time 
procedure 




;s 

1 

The defining word 
is created 

1 

The defining word 
is executed 

1 

which creates 

1 

which creates 



created via the 
defining word 


Figure <BUILDS-1 

Compile Time Action of <BUILDS and DOES> 
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DEFINITION TIME action of <BUILDS (Sequence 1): ( — ) 


DOCOL 


0 


CONSTANT 



This is just a 
h e rrjp 0 rary vslus. 


This simply builds a 
definition header. The 
Code Field and 
Parameter Field 
contents will be 
overlayed by DOES> . 


EXECUTION TIME action of <BUILDS: ( - ) 

<BUILD3 simpiy creates a header for a definition and therefore has no Sequence 2 or Sequence 3 time action. 
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= ( valuel \ value2 — flag ) 

= (pronounced "equals") compares the top two values on the parameter stack and replaces them with a boolean flag. The flag is true (1) 
if the values are equal. The flag is false (0) if the values are not equal. 


smpls of s word which uses — • 

* At entry - The top of the parameter stack contains a signed 16-bit single precision value to be compared for equality with 
the second stack entry, which is also a signed 16-bit single precision value. 

* At exit - The top of the parameter stack contains a boolean flag. The flag is true (1) if the input values were equal and 
false (0) if they were not equal. 


= is a high level colon definition. 

FORTH-79: The FORTH-79 equivalent for = is = . 

Definition: : = ( valuel\ va!ue2 -- flag ) 

- 0 = : 


DOCOL 


0 = 


;S 



Subtracting the two 
values compares them 
for equality. 


A zero will be on the 
stack only if the 
true values were equal. 
0= changes this 0 to a 
true flag because it is 
"true" that the values 
were equal. 
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> 


> ( valuel\ value2 — truth flag ) 

> (pronounced "greater-than") compares the two top-most signed 16-bit values on the parameter stack and replaces them with a truth 
flag. The truth flag is set true (1) if the second value is greater than the top of the stack value and false (0) if it is less than or equal to 
the top of the stack value. 

At execution time, > simply swaps parameters and performs a < comparison. 

* At entry - The top and second parameter stack entries contain the signed 16-bit single precision values to be compared. 

* At exit - The top of the parameter stack contains a truth flag. This flag is set true (1) if the second stack value was 
greater than the top of the stack value. Otherwise, it is set false (0). 

> is a high level colon definition. 

Refer to < . 

FORTH-79: The FORTH-79 equivalent for > is > . 

Definition: : > ( valuel \value2 — flag) 

j SWAP < ; 


DOCOL 


SWAP 


< 


;s 



Set up for ^ 
comparison. 


Since the two values 
were swapped, the 
logical result of this 
operation is identical 
to > . 
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>R 

>R ( value to be placed onto return stack — ) 

>R (pronounced "to-R") pops a number from the top of the parameter stack and pushes it onto the top of the return stack. 

Note: Care must be taken to ensure that the return stack is restored to its original condition before returning to the calling procedure. 
This is usually accomplished through the use of R> (e.g., : NEW-WORD >R . . . . R> ;). 

* At entry - The top of the parameter stack contains the 16-bit value to be placed onto the return stack. 

* At exit - No parameter stack parameters. The top of the return stack contains the value previously on the top of the 
parameter stack. 

>R is a low level code primitive. 

Refer to R> . 

FORTH-79: The FORTH-79 equivalent for >R is >R . 



NEXT 
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9 


? ( address of value to be output — ) 

? (pronounced "question-mark") performs a binary-to-ascii conversion on the signed 16-bit value contents of the specified memory 
location and prints the result on the output device. For example, a variable name followed by ? prints the contents of that variable. 

Tk« «->»->♦- iiaIiia «»-> DA Ctr i« i ■ <-l nni^iv/ 

i i ic luuciil vaiuc ti t i_/noi_ 10 uocu ao ci 10 luiivcioiUti i auiA. 

* At entry - The top of the parameter stack contains the memory address of the 16-bit signed value to be converted and 
printed. 

* At exit - No parameters. 

? is a high level colon definition. 

Refer to D.R . 

FQRTH-79: The FORTH-79 equivalent for ? is ? . 

Definition: : ? ( addres s --) 

(a) . : 


DOCOL 


§ 


;s 



Set up for . . Get 
value to be printed. 
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?COMP 


?COMP ( -) 

?COMP (pronounced "question-compile") issues Error Message 11H and a QUIT (8080 fig-FORTH Version 1.1) if the system is not in 
compile mode. In this case, compile mode is defined as the user variable STATE containing a non-zero value. 

The standard error text for this word is "COMPILATION ONLY, USE IN DEFINITION". 

The exact nature of the action taken when an error message is issued depends upon the contents of the user variable WARNING . (See 
WARNING and MESSAGE ). 

If WARNING contains a 0 value, only the error message number is output and then a QUIT is performed. 

If WARNING contains a positive, non-zero value, the message number is used as an offset (plus or minus) relative to Line 0 of Screen 4. 
(e.g., A message number of 2 results in Line 2 of Screen 4 being displayed.) After the message is issued, a QUIT is performed. 

If WARNING contains a negative value, normally -1, (ABORT) is executed. No message is output. 

7COMP is used by compiler words to ensure that the system is in compile mode. COMPILE and several of the conditional words are 
examples of words which use 7COMP . 

* At entry - No parameters. 

* At exit - No parameters. 

7COMP is a high level colon definition. 

Refer to WARNING , MESSAGE , STATE , ERROR , (ABORT) , QUIT , and COMPILE . 

FORTH-79: There is no FORTH-79 equivalent for 7COMP . 

Definition: : 7COMP ( --) 

STATE la) H* 11 7ERROR : 











?CSP 


?CSP ( -) 

?CSP (pronounced "question-C-S-P") issues Error Message 14H and a QUIT if the current parameter stack pointer position does not equal 
that stored in the user variable CSP . 


T-. _._._r_i-u:__I ttr'yp"C"TK.ITTTHM MOT ITTMTCUCTVI 

me stanaara errur text iui mis wuiu 10 lJct mmun > » « ii n_u^ • 


This is most often used in compiler security since an unbalanced stack often reflects a compilation error. Normally a 1CSP is used to 
save the stack pointer position when beginning compilation (e.g., in :) and ?CSP is used to check it when finishing compiling. 

The exact nature of the action taken when an error message is issued depends upon the contents of the user variable WARNING . (See 
WARNING and MESSAGE). 


If WARNING contains a 0 value, only the error message number is output and then a QUIT is performed. 


If WARNING contains a positive, non-zero value, the message number is used as an offset (plus or minus) relative to Line 0 of Screen 4. 
„ /\ mgssage number of 2 results in Line 2 of Screen 4 being displayed.) After the message is issued, a QUIT is performed. 


If WARNING contains a negative value, normally -1, (ABORT) is executed. No message is output. 


An example of the use of 7COMP can be found in ;CODE . 


* At entry - No parameters. 


* At exit - No parameters. 


?CSP is a high level colon definition. 

Refer to WARNING , MESSAGE , TERROR , STATE , (ABORT) , and QUIT . 


FORTH-79: There is no EORTH-79 equivalent for ?CSP . 


Definition: 


DOCOL 


SP@ 


CSP 


1 


LIT 

14H 


: ?CSP ( -) 

spra csp 



fa) - 14 TERROR ; 


Set up for - . 


Set up for (a) . 


Set up for - . 


Set the flag for 
TERROR . Compare the 
contents of CSP with 
the current position of 
the stack pointer. 


Put the value for trror 
Error Message 14H 
(DEFINITION NOT 
FINISHED) onto the 
stack. 


TERROR 



Display the error 
message (DEFINITION 
NOT FINISHED) if the 
pointers are not equal. 

Note: If an error 
message is issued, a 
QUIT will also occur 
and execution will stop 
here. 
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TERROR 


TERROR ( truth flag \ Error Message Number — ) 

TERROR (pronounced "question-error") issues the specified error message and a QUIT if the truth flag is true (non-zero). 

The exact nature of the action taken when an error message is issued depends upon the contents of the user variable WARNING . (See 
WARNING and MESSAGE). 


If WARNING contains a 0 value, only the error message number is output and then a QUIT is performed. 

If WARNING contains a positive, non-zero value, the message number is used as an offset (plus or minus) relative to Line 0 of Screen 4. 
(e.g., A message number of 2 results in Line 2 of Screen 4 being displayed.) After the message is issued, a QUIT is performed. 

If WARNING contains a negative value, normally -1, (ABORT) is executed. No message is output. 

FORGET is an example of a word which uses TERROR. 


* At entry - The top of the parameter stack contains a signed 16-bit single precision message number value. The second 
stack entry contains a boolean truth flag. 

* At exit - No parameters. 

TERROR is a high level colon definition. 

Refer to ERROR , MESSAGE , WARNING , QUIT , ABORT , and (ABORT) . 


FORTH-79: There is no FORTH-79 equivalent for TERROR . 


Definition: 


DOCOL 


SWAP 


F 


ERROR 


: TERROR 

SWAP 


( flag\error message number ) 

IF ERROR ELSE DROP 


THEN 



Set up for F . Swap 
the error message 
number and the truth 
flag. 



Branch if the truth 
flag was zero, i.e., 
there was no error. 


Truth flag was 
non-zero. Display an 
error message and 
QUIT . 


THEN 



;s 



(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


This is the entry point 
from the "true portion" 
of the IF statement. 


>(QERR2) 


Branch. 


Branch around the 
"false portion" of the 
previous F structure. 


ELSE 



DROP 
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This is the entry point 
for the "false portion" 

- of the IF structure. 

i.e., There was no 
error. 

i _ 

Drop the top value Drop the unused error 
from the parameter message number, 
stack. 












?EXEC 


?EXEC ( - ) 

?EXEC (pronounced "question-execute") issues Error Message 12H and a QUIT if the system is not in execute mode. In this case, 
execution mode is defined as the user variable STATE containing a value of zero. 

-l j i_j je _i itthm u v/ii 

me suandaru error lgxl lur this wOru is laluu iiljin t . 

The exact nature of the action taken when an error message is issued depends upon the contents of the user variable WARNING . (See 
WARNING and MESSAGE). 


If WARNING contains a 0 value, only the error message number is output and then a QUIT is performed. 


If WARNING contains a positive, non-zero value, the message number is used as an offset (plus or minus) relative to Line 0 of Screen 4. 
(e.g., A message number of 2 results in Line 2 of Screen 4 being displayed.) After the message is issued, a QUIT is performed. 

If WARNING contains a negative value, normally -1, (ABORT) is executed. No message is output. 

: (colon) is an example of a word which uses 7EXEC. 

* At entry - No parameters. 

* At exit - No parameters. 

7EXEC is a high level colon definition. 

Refer to WARNING , STATE , ERROR , (ABORT) , and QUIT . 

FORTH-79: There is no FORTH-79 equivalent for 7EXEC . 

Definition: 


bl A It. 


LIT 

12H 


7ERROR 


;s 


7EXEC ( - ) 
STATE ® 


12 7ERROR 



Get the contents of 
STATE . 


Put the number of the 
error message, 
EXECUTION ONLY, 
onto the stack. 


Issue Error Message 12H 
if not in execution 
mode. 

Note: If an error 
message is issued, a 
QUIT will also occur 
and execution will stop 
here. 
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7L0ADING 


7LOADING ( - ) 

7LOADING (pronounced "question-loading") issues Error Message 16H and executes a QUIT if the system is not loadinc, from disk. 

The standard error text for the word is "USE ONLY WHEN LOADING". 

Tk« nnn>ni>iiu ranoiuoe iooiif fiTim (HibU nnaHinnl nr frnm thn tormina! kevboard. The user variable BLK contains a zero if the 

I l ic o J OLC, 11 i riuiniau; iwwtwivww - - "D' - ' — ^ . . 

system is receiving input from the terminal input buffer. 7LOADING tests the contents of BLK and issues the error message if BLK 
contains a zero. 

The exact nature of the action taken when an error message is issued depends upon the contents of the user variable WARNING . (See 
WARNING and MESSAGE ). 

If WARNING contains a 0 value, only the error message number is output and then a QUIT is performed. 

If WARNING contains a positive, non-zero value, the message number is used as an offset (plus or minus) relative to Line 0 of Screen 4. 
(e.g., A message number of 2 results in Line 2 of Screen 4 being displayed.) After the message is issued, a QUIT is performed. 

If WARNING contains a negative value, normally -1, (ABORT) is executed. No message is output. 

—> is an example of a word which uses 7LOADING . 

* At entry - No parameters. 

* At exit - No parameters. 


7LOADING is a high level colon definition. 

Refer to 7ERROR , STATE , MESSAGE , WARNING , (ABORT) , and QUIT . 


FORTH-79; There is no FORTH-79 equivalent for 7LOADING . 

Definition: : 7LOADING ( --) 

BLK fa) 0= 16 7ERROR ; 


DOCOL 


BLK 




0 = 


LIT 

16H 



Set up to get contents 
of BLK . 


Pick up the contents of 
BLK . A value of zero 
signifies that the 
system is inputting 
from the terminal. A 
non-zero value reflects 
the block number being 
loaded. 


Set the flag for 
7ERROR . Make true 
truth flag if BLK 
contained zero (i.e., 
was inputting from 
terminal). 


Set up for 7ERROR . 
Place the number of the 
Error Message, USE 
ONLY WHEN LOADING, 
onto the stack. 


7ERROR 


;S 


_ 

Issue the sf 
error mess 
QUIT if thf 
flag in the 
entry is tri 
(non-zero). 

_ 

jecified 
age and 
truth 
second 

le 



(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


Issue Error Message 16H 
if not loading from the 
disk. 

Note: If an error 
message is issued, a 
QUIT will also occur 
and execution will stop 
here. 
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7PAIRS 


?PAIRS ( valuel \value2 — ) 

7PAIRS (pronounced "question-pairs") issues Error Message 13H and executes a QUIT (8080 fig-FORTH Version 1.1) if the top two 16-bit 
values on the parameter stack are not equal. 

The standard error text for this word is "CONDITIONALS NOT PAIRED". 

This word is normally used during compilation to evaluate compilation conditionals. 

The exact nature of the action taken when an error message is issued depends upon the contents of the user variable WARNING . (See 
WARNING and MESSAGE). 

If WARNING contains a 0 value, only the error message number is output and then a QUIT is performed. 

If WARNING contains a positive, non-zero value, the message number is used as an offset (plus or minus) relative to Line 0 of Screen 4. 
(e.g., A message number of 2 results in Line 2 of Screen 4 being displayed.) After the message is issued, a QUIT is performed. 

If WARNING contains a negative value, normally -1, (ABORT) is executed. No message is output. 

AGAIN is an example of a word which uses 7PAIRS . 

* At entry - The first and second parameter stack entries contain 16-bit values to be compared for an equal condition. 

* At exit - No parameters. 


7PAIRS is a high level colon definition. 

Refer to 7ERROR , WARNING , MESSAGE , STATE , (ABORT) , and QUIT . 


FORTH-79: There is no FORTH-79 equivalent for 7PAIRS . 

Definition: : 7PAIRS ( valuel \value2 —) 

- 13 7ERROR ; 


DOCOL 


LIT 

13H 


7ERROR 


JS 



Set up for 7ERROR . 

A result of zero means 
that the two values are 
equal. Else, the value 
will be not zero. 


Set up for 7ERROR . 
Put the number of the 
error message, 
CONDITIONALS NOT 
PAIRED, onto the 
stack. 


Issue Error Message 13H 
if the two values were 
not equal. 

Note: If an error 
message is issued, a 
QUIT will also occur 
and execution will stop 
here. 
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?STACK 

7STACK ( - ) 

7STACK (pronounced "question-stack") checks for stack underflow and stack overflow and executes 7ERROR if either condition has 
occurred. 


Stack underflow generally occurs when the stack pointer "backed up" behind the initial starting location. 


Stack overflow generally occurs when the stack has "grown" into the PAD area just below the end of the dictionary. 


The exact determination of stack underflow and overflow is installation dependent which makes 7STACK an installation dependent 
word. 


The standard error text for this word is "EMPTY STACK" and "STACK OVERFLOW". 

The exact nature of the action taken when an error message is issued depends upon the contents of the user variable WARNING . (See 
WARNING and MESSAGE ). 


If WARNING contains a 0 value, only the error message number is output and then a QUIT is performed. 


If WARNING contains a positive, non-zero value, the message number is used as an offset (plus or minus) relative to Line 0 of Screen 4. 
(e.g., A message number of 2 results in Line 2 of Screen 4 being displayed.) After the message is issued, a QUIT is performed. 

If WARNING contains a negative value, normally -1, (ABORT) is executed. No message is output. 

INTERPRET is an example of a word which uses 7STACK. 

* At entry - No parameters. 

* At exit - No parameters. 

7STACK is a high level colon definition. 

Refer to ERROR , WARNING , MESSAGE , QUIT , ABORT , and (ABORT) . 


FORTH-79: There is no FORTH-79 equivalent for 7STACK . 


Definition: 


DOCOL 


sp@ 


so 


1 


7STACK 

(-) 



SPfa) 

SO O SWAP 

LX 1 7ERROR 

SP!a) HERE 80 + 

IX 7 

7ERROR ; 






Set up for LX . Get the 
current stack pointer 
value. 


Set up for (a) . SO 
contains the initial 
value of the stack 
pointer. 


Fetch the initial value 
of the stack pointer. 


SWAP 


IX 


1 


7ERROR 



A SWAP is necessary 
because the SP(a) had to 
be performed first so 
as not to affect the 
stack location with the 
SO @ . 


Set truth flag for 
7ERROR . Note: This 
is an unsigned 
comparision. The fig- 
FORTH model uses < 
which is signed and can 
cause errors if an 
address is greater than 
7FFF (H). 


Set up for 7ERROR . 
Place the number of the 
error message, EMPTY 
STACK, onto the stack. 


Issue Error Message 1 
if stack underflow has 
occurred. 

NOTE: If an error 
message is issued, a 
QUIT will also occur 
and execution will stop 
here. 
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Now test for stack 
overflow, i.e., 
Determine if the stack 
has grown to within 128 
bytes past the end of 
the dictionary. 


Place the address of 
the stack position 
onto the top of the 
parameter stack as 
it was before SP(§ 
was executed._ 


Set up for LX . Again, 
get present stack 
pointer location. 


Place the address of 
the next available 
dictionary location 
onto the top of the 
parameter stack. 


gives the address of 
the end of the 
dictionary. 


Place the literal 
value 80H onto the 
top of the parameter 
stack. 


Set up for + . This is 
the length of PAD and 
the text buffer for 
this installation. 


Add the top two 
stack values and 
replace them with 
their signed sum. 


Set up for LX . 
Calculate the upper 
most limit for the 
stack. 


Replace the top two 
stack values with a 
true flag (1) if the 
top stack's absolute 
value is less then 
the second stack 
entry's absolute 
value. 


Set the truth flag for 
TERROR . Test if 
overflow has occurred. 
Note the unsigned 
comparison. 


TERROR 


Place the literal 
value 7H onto the 
top of the parameter 
stack. 


Issue the specified 
error message and 
QUIT if the truth 
flag in the second 
entry is true 
(non-zero)._ 


Set up for TERROR . 
Put the number of the 
error message, STACK 
OVERFLOW, onto the 


Issue Error Message 7H 
if stack overflow has 
occurred. 

Note: If an error 
message is issued, a 
QUIT will also occur 
and execution will stop 
here. 


(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 
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7TERMINAL 


7TERM1NAL ( - flag ) 

7TERMINAL (pronounced "question-terminal") is an installation dependent word that is normally used to determine if there is a character 
ready to be input from a terminal. 

This word is sometimes used to determine first if the break key has been pressed; then if any other key has been pressed. 

INDEX is an example of a word which uses 7TERMINAL . 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains a truth flag. 

A true flag (1) indicates that a character is ready. KEY can then be used to read that character. 

A false flag (0) indicates that no key has been pressed. 

7TERMINAL is a low level code primitive. 

FORTH-79: There is no FORTH-79 equivalent for 7TERMINAL . 



NEXT 
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(a) ( memory address — 16 -bit memory contents ) 

(§ (pronounced "fetch") replaces the 16-bit address on the top of the parameter stack with the 16-bit memory contents of that address, 
[a) is the primary means in FORTH of accessing data stored in memory. 

NOTE: This word "fetches" word (16 bit) values; C(a) is used to fetch byte (8 bit) values. 

LOAD is an example of a word which uses (§. 

* At entry - The top of the parameter stack contains the 16-bit address of the memory word to be fetched. 

* At exit - The top of the parameter stack contains the 16-bit contents of the specified memory word. 

(a) is a low level code primitive. 


.c_ 

IXC I Cl LU L_^(OJ • 

FORTH-79: The FORTH-79 equivalent for (a) is (a) . 



NEXT 
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ABORT 

ABORT ( - ) 


ABORT can be considered the warm start routine for the FORTH system. ABORT resets the parameter stack, displays a start up 
message, sets CONTEXT and CURRENT to FORTH , sets BASE to DECIMAL , and issues a QUIT (which stops any compilation and starts 
interpretation from the input terminal). 

ABORT is commonly called by (ABORT) when WARNING is -1 and an error condition has been detected. 

COLD is an example of a word which uses ABORT . 

* At entry - No parameters. 

* At exit - No parameters. 


ABORT is a high level colon definition. 
Refer to (ABORT) , COLD , and QUIT . 


FORTH-79: The FORTH-79 eguivalent for ABORT is ABORT . 


Definition: 


DOCOL 


sp: 


DECIMAL 


7STACK 


CR 


.CPU 


(.") 


ODH 


FIG-FORTH 


: ABORT ( - ) 

SPI DECIMAL ?STACK CR .CPU ." FIG-FORTH 8080 VER 1.1 " 
FORTH DEFINITIONS QUIT ; 



8080 fig-FORTH 
Version 1.1 


Make sure the stack is 
within bounds. 


Print the following 
output message. 

Print 13 characters 
including the release 
and version number. 


This prints the 
character string 
"FIG-FORTH". 


FIGREL+30H 

ADOT 

FIGREV+30H 


FORTH 


DEFINITIONS 


QUIT 


;S 



This prints the release 
and version number. 
e.g., In the 8080 
Version 1.1 listing it 
would be "1.1". 


Initialize CONTEXT to 
aim at the FORTH 
vocabulary. 


Initialize CURRENT to 
aim at the FORTH 
vocabulary. 


Initialize data stream 
input to come from the 
terminal. 


Note: The above QUIT 
never allows this ;S 
to execute. 
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ABS 


ABS ( signed value — absolute value ) 

ABS (pronounced "absolute") converts a signed single precision value on the top of the parameter stack into its absolute unsigned value. 
M* is an example of a word that uses ABS . 

* At entry - The top of the parameter stack contains a 16-bit signed value. 

* At exit - The top of the parameter stack contains a 16-bit unsigned absolute value. 

ABS is a high level colon definition. 

FORTH-79: The FORTH-79 equivalent for ABS is ABS . 

Definition: : ABS ( signed value -- absolute value ) 


DOCOL 


DUP 




Set up for +- . 
Duplicate original 
signed value. 

If value is positive, 
nothing happens. If 
negative, the value is 
negated, making it 
positive (i.e., 
absolute value). 


91 







AGAIN 


AGAIN 

COMPILE TIME: ( loop address \ 1 — ) 

(Sequence 2) 

EXECUTION TIME: ( - ) 

(Sequence 3) 

AGAIN is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution 
time. 

AGAIN is used to mark the end of an infinite loop structure in the form: 

BEGIN "Loop Body" AGAIN 

There is no exit from a BEGIN-AGAIN loop. If an exit is necessary, another type of loop structure should be used. 

BEGIN-AGAIN loop structures must always be used within a colon definition. 

The compile time action (Sequence 2) of AGAIN is to compile a BRANCH into the dictionary. Secondly, it resolves the loop body entry 
point address provided by BEGIN into a return branch offset used by BRANCH and stores this offset into the dictionary. 

Some compiler security is provided by checking for a 1 on the top of the stack. BEGIN leaves a 1 on the stack. Since no other compiling 
words leave a 1 on the stack, failure to pair an AGAIN with a BEGIN will cause an error condition to be detected by 7PAIRS . Note that 
this is not foolproof. 

The execution time action (Sequence 3) of AGAIN is to unconditionally branch back to its corresponding BEGIN (i.e., the beginning of the 
"loop body"). AGAIN accepts no input parameters and leaves nothing on the stack. 

The BRANCH , compiled into the definition at compile time, is what performs the looping. 

AGAIN may only be used within a colon ( :) definition. 

Note that AGAIN is an IMMEDIATE word. This means that its precedence bit is set, and it will therefore execute at compile time. 

QUIT is an example of a word which uses AGAIN. 


COMPILE TIME (Sequence 2): 

* At entry - The top of the parameter stack contains the 16-bit signed single precision value 1 used for compiler security. 

The second stack entry contains the 16-bit entry point address of the "loop body" portion of the BEGIN-AGAIN structure. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - No parameters. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

COMPILATION ONLY (UH) — This word may only be used within a colon definition. 

CONDITIONALS NOT PAIRED (13H) — There is some sort of problem with the pairing of conditionals within the definition being 
compiled. 

AGAIN is a high level colon definition. 

Refer to BEGIN , and BRANCH . 

FORTH-79: AGAIN is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". 

Definition: : AGAIN ( loop address\1 -- ) ( compile time ) 

1 7PAIRS COMPILE BRANCH BACK ; IMMEDIATE 
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COMPILE TIME action of AGAIN : ( loop address 1 — ) 
(Sequence 2) 


EXECUTION TIME action of AGAIN : ( — ) 
(Sequence 3) i 


DOCOL 


1 


7PAIRS 


COMPILE 


BRANCH 


BACK 


;S 


IMMEDIATE 



I BEGIN 

V(j 


BEGLOOP 


> 


set up tor rt-Mir^o 


An AGAIN with a 
corresponding BEGIN 
will result in a 1 left 
on the top of the 
stack. An error message 
will be issued and a 
QUIT will occur if not. 


This puts BRANCH into 
the definition being 
compiled. 


BRANCH is compiled 
into the definition. It is 
not executed at compile 
time. 


BRANCH 


Entry point to 
beginning of "loop 
body". 


"Loop body". 


Unconditionally 
branch back to the 
beginning of the 
"loop body". BRANCH 
is the run time 
portion of AGAIN . 


BEGLOOP y—- 




Branch back to BEGIN 
using the previously 
calculated and stored 
backwards offset. 


There is no exit 
from a BEGIN-AGAIN 
loop. 


The address left by 
BEGIN is used to 
calculate a return 
branch offset. This 
offset is then compiled 
into the definition and 
referenced by BRANCH 
at execution time. 


AGAIN is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 
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ALLOT 

ALLOT ( number of storage locations — ) 

ALLOT advances the Dictionary Pointer (DP) the specified number of storage locations. Its primary purpose is to reserve or "allot" 
memory space in the dictionary. The particular length of a storage location is dependent upon the address type of the processor used. 

." is an example of a word which uses ALLOT . 

* At entry - The top of the parameter stack contains a 16-bit signed number specifying the number of storaqe locations to 

be allotted. 3 

* At exit - No parameters. 

ALLOT is a high level colon definition. 

Refer to DP . 

FORTH-79: The FORTH-79 equivalent for ALLOT is ALLOT . 

Definition: : ALLOT ( number —) 

DP +'. ; 


DOCOL 


DP 


;S 



DP is the Dictionary 
Pointer. 


Allot the space, i.e., 
Add the number of 
locations to allot to 
the next available 
dictionary location 
pointer. 
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AND 


AND ( valuel\ value2 — logical result) 

AND performs a bit-wise logical AND function on the top two values on the parameter stack and replaces them with their logical result- 
BUFFER is an example of a word which uses AND. 

* ^ entry - The top of stack and second entry contain the 16-bit values to be ANDed. 

* At exit - The top of the stack contains the 16-bit logical result. 

AND is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for AND is AND . 



stack. 

NEXT 


95 








B/BUF 


B/BUF ( — bytes per buffer ) 

B/BUF (pronounced "bytes-per-buffer") is a single precision CONSTANT value. This constant places the number of bytes per disk buffer 
onto the top of the parameter stack. This value reflects the number of bytes transferred between mass-storage and memory by 
BLOCK . 

The number of buffers in a system can be determined usinq B/BUF by subtracting FIRST from LIMIT and then dividing the result by 
B/BUF (i.eLIMIT FIRST - B/BUF / ). 

( LINE ) is an example of a word which uses B/BUF. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the signed 16-bit single precision value of the number of bytes per disk 
buffer. 

Refer to BUFFER , +BUF , BLOCK , LIMIT , and FIRST . 

FORTH-79: B/BUF is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". Note that the size of 
a FORTH-79 buffer is 1024 bytes (IK). 
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B/SCR 


B/SCR ( — blocks per screen ) 

B/SCR (pronounced "blocks-per-screen") is a single precision CONSTANT value. This constant places the number of blocks per editing 
screen onS the top of the parameter stack. By convention, an editing screen in FORTH contains 1024 (dec.mal) or IK characters. The 
screen is normally organized into 16 lines of 64 characters. The constant C/L specifies how many characters are used per editing line. 

MESSAGE is an example of a word which uses B/SCR. 


* At entry - No parameters. 

* At exit - The top of the parameter stack contains the signed 16-bit single precision value of the number of blocks per 
editing screen. 

FORTH-79: There is no FORTH-79 equivalent for B/SCR . 



BACK 


BACK ( entry point address — ) 


BACK is primarily used while compiling loop structure words at Sequence 2. 
BACK ) branch offset and compiles the offset into the dictionary. 


It resolves the supplied address into a backwards (hence 


r3 m PIs, during compilation (Sequence 2), DO supplies the beginning address 
LOOP ) converts this address into an offset and then compiles it for (LOOP) 
(Sequence 3). 


of the "loop body" to LOOP . BACK (contained within 
to use when "branching back" during execution time 


LOOP is an example of a word which uses BACK. 

* At entry - The top of the parameter stack contains a 16-bit entry point address. 

* At exit -No parameters. 

BACK is a high level colon definition. 

NOTE: Although BACK is a word used by compiler words, it is not an IMMEDIATE word itself. 
Refer to DO , and LOOP . 


FORTH-79: There is no FORTH-79 equivalent for BACK 

Definition: : BACK ( entry point address -) 

HERE - , ; 


DOCOL 


HERE 


;S 



Set up for - . Get the 
address of where the 
offset will go. 


Calculate the offset. 
(Offset address minus 
entry point address.) 


Compile the offset into 
the definition. 


90 









BASE 


BASE ( — data address ) 

BASE is a user variable that contains the current number base (or radix) used for input and output numeric conversion. 

HEX and DECIMAL are examples of words that set BASE . Executing HEX stores a 16 (decimal) into BASE . Executing DECIMAL stores 
a 10 (decimal) into BASE . 

. ("dot") references BASE when performing a binary-ascii conversion. 

(NUMBER) references BASE when performing ascii-binary conversion. 

Note that the seguence BASE ? will always result in a "10" being output no matter what base the system is in. Since this is the 
correct answer, use the sequence BASE @ 1 - . which will print a "9" for a DECIMAL base, an "F" for a HEX base, etc. Another 
alternative is defining the word BASE? . : BASE? BASE § DUP DECIMAL . BASE I ; This word will display the base in decimal 

without destroying the contents of BASE . 

The user variable BASE is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable BASE . 

Refer to HEX , DECIMAL , (NUMBER) , . , and USER . 

FORTH-79: The FORTH-79 equivalent for BASE is BASE . 
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BEGIN 


BEGIN 

COMPILE TIME: ( — entry point address \ 1) 

(Sequence 2) 

EXECUTION TIME: ( - ) 

(Sequence 3) 

BEGIN is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution 
time. 

fOTms^ ^ USed t0 marl< the beginning of an indefinite > repetitive loop structure. It is used as the beginning of three types of loops in the 


BEGIN "Loop Body" UNTIL 
BEGIN "Loop Body" AGAIN 

BEGIN "Set Conditional" WHILE "True Portion" REPEAT 
A BEGIN-type loop structure must always be used within a colon definition. 

BEGIN-type loops differ from DO-LOOP's in that a BEGIN loop is not limited from its start to a specified number of passes through the 
loop as is a DO-LOOP . Once started, a BEGIN-type loop may execute indefinitely; or for some structures, until a specified condition is 
met. 

The compile time action (Sequence 2) of BEGIN is very simple. BEGIN places the address of the next available dictionary location onto 
the parameter stack, (i.e., It passes the beginning address of the "loop body" to UNTIL , REPEAT or AGAIN so that these words can 
compile a return branch into their respective definitions.) 

To provide compiler security, the value 1 is placed onto the top of the parameter stack so that UNTIL , AGAIN , WHILE or REPEAT can 
check for it. This provides a somewhat secure (but not foolproof) method of checking for un-balanced loop structures. 

The apparent run time action (Sequence 3) of BEGIN is to serve as a return entry point for the "loop back" word at the end of the 
structure. (Really BEGIN does nothing because the branch which is executed is actually imbedded within the "loop back" definition.) 

Note that BEGIN is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 

QUIT is an example of a word which uses BEGIN. 


COMPILE TIME (Sequence 2): 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the 16-bit signed single precision value 1 used for compiler security. 
The second stack entry contains a 16-bit address specifying the location of the first word of the "loop body". 

EXECUTION TIME (Sequence 3): 

* At entry - No parameters. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

COMPILATION ONLY (UH) — This word may only be used within a colon definition. 

BEGIN is a high level colon definition. 

Refer to UNTIL , AGAIN , WHILE , and REPEAT . 

FORTH-79: The FORTH-79 equivalent for BEGIN is BEGIN . 

Definition: : BEGIN ( — entry point address \1 ) ( compile time ) 

7COMP HERE 1 ; IMMEDIATE 
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COMPILE TIME action of BEGIN (Sequence 2): ( — entry point address \ 1 ) 


DOCOL 


?CGMr 


HERE 


1 


;s 


IMMEDIATE 



Ul_Uil N I I IUOL L»0 UOCU 

within a colon 
definition. 


Get the location of the 
beginning of the loop 
body. 


UNTIL AGAIN WHILE 
and REPEAT all expect 
1 on the top of the 
stack. 


BEGIN is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


EXECUTION TIME action of BEGIN (Sequence 3): ( — ) 


There is no run time action for BEGIN . 
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BL 


BL ( - 20H ) 

BL (pronounced "B-L") is a single precision CONSTANT value. This constant places the ascii value for the character "blank" (or "space") 
onto the top of the parameter stack. This value is a 20 (hex) or a 32 (decimal). Referencing a blank via the name BL makes FORTH 
more readable. 


allows less chance of introducing a "wrong base" bug. For example, if the editing screen is in decimal base, a blank is a 32; if the base is 
hex, a blank is a 20. This is sometimes a source of error. 

-FIND is an example of a word which uses BL. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the signed 16-bit single precision value of an ascii blank character. 

Refer to WORD . 


FORTH-79: There is no FORTH-79 equivalent for BL . 
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BLANKS 


BLANKS ( beginning address \ # of bytes to blank — ) 

BLANKS clears a specified region of memory to ascii blanks (20H). 
BLANKS is simply a FILL with the fill character (20H) "hard coded". 


* At entry - The top of the parameter stack contains the beginning address of the memory to fill. The second stack entry 
contains the positive 16-bit number of bytes (8080 fig-FORTH version) to fill. 

* At exit - No parameters. 

BLANKS is a high level colon definition. 


Refer to FILL . 

FORTH-79; BLANKS is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". 


Definition: : BLANKS ( beginning address\# --) 

BL FILL ; 


DOCOL 


BL 


FILL 


;S 



Set up for FILL . Set 
20H as FILL character. 
The stack now contains; 
20H 

jr of Bytes 
Beginning Address 


Fill memory with 
blanks. 
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BLK 

BLK ( — data address ) 

BLK (pronounced "B-L-K") is a user variable which contains the number of the block currently being interpreted. If BLK contains a zero, 
the input data stream is from the terminal. 

WORD references BLK to determine the address of the input data stream. 

LOAD and —> set BLK with the mass storage block being transferred to memory. 

QUIT sets BLK to 0, meaning that input is from the terminal. 

The user variable BLK is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable BLK . 

Refer to WORD , LOAD , —> , and USER . 

FORTH-79: The FORTH-79 equivalent for BLK is BLK . 
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BLOCK 


BLOCK ( desired block number — data address of desired block ) 


BLOCK is used to access data kept in mass storage. (Since disk is the most common mass storage, further references will be to "disk" 
and not "mass storage".) BLOCK is a virtual memory type access word. This means that the desired block number is replaced with the 
memory address of that block. The type of storage, the device number and other physical attributes may be treated as being transparent 
to the external operation of the word. This also means that data that has been flagged as modified, 
written back to disk before that location is overwritten with new disk data. 


ifK « rtK oh *11 


BLOCK transfers data from disk to a buffer. A FORTH system normally contains several physically contiguous buffers, with the last 
buffer "linked" by software (see +BUF ) back to the first buffer to form a "logically circular" array of buffers. (Refer to +BUF for a 
more complete description of these buffers.) 

The management of these buffers falls into two separate (but related) categories; buffer-referencing and buffer-allocation/disk access. 

The function of buffer-referencing management is to minimize disk accesses. BLOCK 's primary responsibility is to perform 
buffer-referencing management. If buffer-allocation is necessary, BLOCK calls BUFFER (see BUFFER ). 

The basis of buffer-referencing management is to possibly save a disk access by first examining all buffers in the buffer array to 
determine if the desired block is currently in memory. The search begins with the most recently referenced buffer (pointed to by the 
system variable PREV ), and proceeds cyclically through the buffer array until, if no match is found, it returns again to the most recently 
referenced buffer. Note that although the search takes place sequentially in the direction of buffer -allocation, there is no guarantee 
that the search takes place in descending order of the most recently referenced to least recently referenced buffer. This is because 
there is only one referencing-pointer ( PREV ) and references to blocks in memory buffers may take place in any random order. 

Buffer-referencing management works because references to blocks are usually concentrated within the same set (but not necessarily 
numerically close range) of block numbers. 

As previously described, if a newly allocated buffer has been flagged as being modified (see UPDATE ); the contents of that buffer is 
written to disk and not just overlayed with the new data. An updated buffer may be forced to disk before this allocation process by using 
the word FLUSH . 

It is extremely important to note that the size of a buffer (i.e., the number of bytes read by BLOCK) is an arbitrarily set value. This 
value is stored in the constant B/BUF . This means that while the buffer size may correspond to the sector size of the disk being used, it 
does not have to. It also means that in a fig-FORTH system, BLOCK does not automatically read in a IK byte source screen. (This is a 
possible source of confusion to those switching between fig-FORTH and some FORTH, Inc., type systems, i.e. In fig-FORTH, a BLOCK is 
not necessarily synonymous with a screen.) 

The word R/W performs the physical device selection and data transfers. Each storage device in the system has a unique range of block 
numbers assigned to it. This allows each block in the system to be unique. It is also in keeping with the virtual aspect of BLOCK in that 
device selection is based solely upon block number range, (e.g., Drive 0 may contain blocks 1 through 799; while Drive 2 may contain 
blocks 800 through 1199, etc.) 

This explicit addressing does pose a slight problem, however. For example; it is difficult to remember that certain data on a diskette 
may reside at block 160 when the diskette is in Drive 1; but that, when the diskette is in Drive 2, that same data on the same diskette 
may reside at block 560. 

BLOCK solves this problem through the use of the user variable OFFSET . Immediately upon entry, the contents of OFFSET is added to 
the desired block number. This allows implicit drive selection by previously setting (i.e., biasing) OFFSET to the starting block number of 
the selected drive, (See DRO and DR.l.) Explicit block addressing may be performed by ensuring that OFFSET contains the value 0 
before calling BLOCK . 

( LINE ) is an example of a word which uses BLOCK. 

* At entry - The top of the parameter stack contains the 16-bit value specifying the desired block number. The maximum 
block number range is from 0 to 32767. The most-significant bit must be 0 as this is used as the "update" flag. 

* At exit - The top of the parameter stack contains the 16-bit memory address of the data portion of the desired block. 


BLOCK is a high level colon definition. 

Refer to BUFFER , B/BUF , UPDATE , FLUSH , OFFSET , DRO , DR1 , and R/W . 


FORTH-79: The FORTH-79 equivalent for BLOCK is BLOCK . 


Definition: 


BLOCK ( block number — address ) 


OFFSET fa) + >R 

IF 

PREV 

fa) DUP 

fa) R - 

BEGIN 




+BUF 0= 

IF 

DROP R 

BUFFER 

DUP fa) 

R - 

DUP + 0= 


UNTIL 

DUP PREV 1 




THEN R> DROP 

2+ 

5 



DUP + 


DUP R 1 R/W 


2 


THEN 
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(block) 

Buffer referencing 
Management 


Calculate absolute 
block number. 


Y 


Check next buffer to 
determine if desired 
block is already in 
memory. 




DOCOL 


OFFSET 


@ 


+ 


>R 


PREV 




Figure BLOCK-1 DUP 

High Level Flowchart of BLOCK 


(§ 


R 



Set up for @ . OFFSET 
is set by DRO or DR1 to 
allow switching between 
drives. (Refer to 
DRO .) 


Pick up the number of 
blocks to offset. 


Add the offset to the 
desired block number. 


Temporarily save the 
desired block number on 
the return stack. 


Now determine if the 
desired block number ^ 
equals that pointed 
to by PREV . 


Set up for @ . PREV 
contains the address of 
the most recently 
referenced disk buffer. 


Get the address of the 
most recently 
referenced disk buffer. 


Duplicate the block 
address for future use. 
(Beginning address + 
BUF .) 


Get the block number of] 
the block pointed to by 
PREV . 


Set up for - . Get the 
desired block number 
from the return stack. 
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DUP 


+ 



Compare the desired 
number with the most 
recently referenced 
block number. 


Set up for + . 

Duplicate the truth 
flag left by comparing 
desired number with the 
most recently 
referenced block 
nu mber. 

The presence of a set 
update bit in the 
buffer will cause the 
comparison of the two 
block numbers to leave 
a misleading flag. 
Adding the flag to 
itself strips off this 
update bit (MSB), if it 
was set, by causing an 
overflow thus leaving a 
correct flag. 


IF 


DROP 


R 


BUFFER 


rp 


{ Perform buffer- 
referencing > 
management. 



block number is equal 
to the last referenced 


block number. Therefore 
the data is already in 
memory and its address 
is available. 


DUP 


R 


BEGIN 



Entry point for "UNTIL 
portion" of BEGIN- 
UNTIL structure. 


Otherwise, scan the 
other remaining disk 


^buffers to determine if^ 
the desired block is 
already in memory. 


J Chain to the nextL 
[buffer. _J 


1 


R/W 


+BUF 


0 = 



+BUF returns an address 
and a truth flag which 
is false (0) when the 
returned address equals 
that in PREV . 


Set up for F . 
Complement the truth 
flag so the "true 
portion" of the F will 
be executed if the 
returned address equals 
that in PREV . 


2 



Drop the top value 
from the parameter 
stack. 


9>(bLOC3) 


Branch if the next 
buffer address does not 

o^uai uiaL in r i\i_» • 

i.e., All buffers have 
not been examined so do 
not perform disk access 
yet. 

I Otherwise, access the 
■"I disk and read in the r 
I desired block. f 


Drop the buffer address 
provided by +BUF . 


Copy the value on 
the top of the 
return stack onto 
the top of the 
parameter stack. 


Set up for BUFFER 
Get the desired 
block number. 


1 Assign and 

place the 

This prepares the least 

data area address of 

recently allocated 

the next available 

buffer location to 

buffer onto the top 

receive a sector of the 

of the parameter 

desired block from disk 

stack. Write the 

and stores the block 

buffer to disk if 

number into it. (i.e., 

the update bit is 

perform buffer 

1 

] act. 


allocation management.) 



Duplicate the top 

Set up for - and R/W . 

value on the 

Duplicate the buffer 

parameter stack. 

data address so it can 



be changed later to the 
buffer address. 


Copy the value on 
the top of the 
return stack onto 
the top of the 
parameter stack. 


Place the constant 
value 1 onto the top 
of the parameter 
stack. 


Perform a physical 
mass storage access 
and either read/ 
write one block of 
data from/to the 
device. __ 


Set up for R/W . Get 
the desired block 
number. 


Set up for R/W . A 1 on 
the stack signifies a 
read. 


This actually performs 
the read Df one sector 
into the previously 
selected buffer 
location. 


Place the constant 
value 2 onto the top 
of the parameter 
stack. 


Set up for - . 
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The data portion of a 
buffer is preceded by 
two bytes of block 
number data. Back up 
and point to the 
beginning of the 
buffer. 


This is the entry point 
from the previous IF . 


Now set up the condi¬ 
tional flag for the 
UNTIL by determining 
if the current buffer 
contains the desired 
block number. 


Duplicate the buffer 
address on the top of 
the parameter stack. 


Pick up the block 
number of the buffer. 


Get the desired block 
number again. 


Compare the desired 
block number with the 
current buffer's block 
number. 


Set up for + . 

Duplicate the result of 
the comparison. 


The presence of a set 
"update" bit in the 
buffer will cause the 
comparison of the two 
block numbers to leave 
a misleading flag. 

Adding the flag to 
itself strips off this 
update bit (MSB), if it 
was set, by causing an 
overflow thus leaving a 
correct flag. 

Set up for UNTIL . 
Complement the boolean 
value left by + . If 
the block numbers are 
equal, the flag will be 
0 but UNTIL will 
continue looping if 
given a 0; so the 0 
must be made a 1, and 
vice versa. 


UNTIL 



■^>(bLOC2) 
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BRANCH 


BRANCH ( - ) 

This execution time (Sequence 3) code is compiled into a definition (during Sequence 2) by ELSE , AGAIN , LOOP , +LOOP , and REPEAT 
to cause an unconditional branch. 

NOTE: At entry IP will be aiming at an offset which is added to IP to cause either a forward or backward branch. 

Also note that negative branch address can be obtained by using a "two's complement" value of the offset. 

* At entry - No parameters. 

* At exit - No parameters. 

BRANCH is a low level code primitive. 

Refer to ELSE , AGAIN , LOOP , +LGGP , and REPEAT . 

FORTH-79: There is no FORTH-79 equivalent for BRANCH . 



NEXT Execute the next word 


using the newiy 
calculated IP address. 
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BUFFER 

BUFFER ( block number — data address ) 

BUFFER is a buffer management word used to obtain the address of a buffer which may then be used for transfer of data from mass 
storage (usually disk) to memory. BUFFER also writes the data portion of any buffers flagged as "updated" to disk. 

There are two forms of buffer management in FORTH: buffer-referencing and buffer-allocation/disk access. 

The buffer-referencing management is primarily the responsibility of BLOCK (see BLOCK). Buffer-referencing management keeps 
track of which buffer was most recently referenced on the supposition that it is likely that this buffer will be referenced again. If the 
most-rec^ntly-referenced buffer does not contain the desired block number/data, the remaining buffers are also examined. If it is 
determined that the data is not already in memory, the data must be read from disk. Before any data transfer can occur, a buffer must 
be allocated. It is the purpose of BUFFER to perform and manage this allocation process. 

The way in which buffers are allocated is closely related to the way buffers are logically arrayed in memory. A FORTH system normally 
contains several physically contiguous buffers wtih the last buffer "linked" via +BUF back to the first buffer to form a "logically circular" 
array of buffers. 

A buffer address is obtained via the word +BUF . (See +BUF for a more detailed explanation of the buffer structure.) Given a buffer 
address, +BUF always returns the address of the next logical buffer in the circular queue. 

Buffer allocation is performed on the basis of the "oldest allocated" buffer being re-allocated for use as the "newest allocated" buffer. 
(The only exception to this method is when the most recently referenced buffer, pointed to be PREV , would be overlayed. Since it is 
likely that the data in this buffer will be referenced again, it is wise not to allocate and overlay the contents of this buffer.) 

Since BUFFER uses +BUF to obtain the address of the next buffer to allocate, buffer-allocation is also "circular". This "circular" 
allocation automatically causes the "oldest allocated" buffer to be used for re-allocation. 

BUFFER stores the address of the next buffer to allocate (i.e., "use") into the system variable USE . Note that this is the next buffer to 
allocate, not the one just allocated. 

Another function of buffer is to write data which has been flagged as "updated" or changed (see UPDATE ) to disk. This prevents data 
which has been modified and flagged as updated from being overwritten with new data. This contributes to the virtual memory action of 
BLOCK by making explicit writes to disk of modified data unnecessary. 

It is extremely important to note, however, that the simple act of modifying data in a buffer will not cause it to be written back to 
disk. The update flag must be set in order for this to occur. 

It is also equally important to note that setting the update flag does not absolutely guarantee that data will be written to disk. This 
write only occurs when a buffer is allocated. If the system is restarted, or powered off, or the desired disk is removed from the drive; 
the data will not be written to the desired location. This problem is easily solved, though, by using the word FLUSH to force all updated 
buffers to be written to disk before allowing any of the conditions mentioned above to occur. 

* At entry - The top of the parameter stack contains a 16-bit unsigned block number which will be assigned to the newly 
allocated buffer. 

* At exit - The top of the parameter stack contains the 16-bit address of the beginning address of the data portion of the 
newly allocated buffer. 

BUFFER is a high level colon definition. 

Refer to BLOCK , +BUF , USE , PREV , and FLUSH . 

FORTH-79: The FORTH-79 equivalent for BUFFER is BUFFER . 

Definition: : BUFFER (block number — address ) 


USE la) 

DUP 

>R 





BEGIN 

+BUF 

UNTIL 





USE 1 

R fa) 

0< IF R 2+ 

r 

7FFF AND 

0 R/W 

THEN 

R '. R 

PREV 

I R> 2+ ; 
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( BUFFER J 


DOCOL 


USE 


a 


DUP 


>R 


Figure BUFFER-1 
High Level Flowchart of BUFFER 


.(buffi)- 


+BUF 


[(Run time portion of 
) Save IP and 
start interpreting 
this definition. 


£ 


Pick up the address of 1 
the buffer to allocate^ 


Place the address of 
the system variable 
USE onto the top of 
I ths par< 




Replace the address 
on the top of the 
| parameter stack with 
the memory contents 
of that address. 


USE contains the 
address of the block 
buffer to "use" (i.e., 

f/N rtllrtrtofo rvrt\/ 
tU QtlUV.Ql.0 I 


Set up for +BUF . Get 
the buffer address 
contained in USE . 
i.e., The address of 
the buffer that is 
going to be allocated. 


Duplicate 
value on tl 
parameter 

the top 
le 

stack. 

Set up for >R . 



Remove the top value 
of the parameter 
stack and place it 
onto the top of the 
return stack. 

Temporarily save the 
address of the buffer 
to allocate. 


< 


Replace the buffer 
address on the top 
of the parameter 
stack with the 
address of the next 
buffer in the 
logically circular 
buffer array. Leave 
a truth flag of 0 if 
the address equals 
that in PREV . 


The following loop gets 
the address of the next 
buffer to allocate 
while ensuring that it 
is not the most 
recently referenced 
buffer. This will not 
work on a system with 
only one buffer. 

TKie je fho Opfrry pQ?n£ 

from the UNTIL portion 
of this BEGIN-UNTIL 
structure. 


Get the address of the 
buffer which has been 
allocated for the 
longest amount of time, 
i.e., the oldest 
buffer. 


Ill 
















^ Is \ 
truth flag 
^ = 0 ? ^ 



/ 18 \ 

<T truth flag 

\ = 0 

Copy the value on 
the top of the 
return stack onto 
the top of the 
parameter stack. 


If the oldest allocated 
buffer is also the most 
recently referenced 
buffer that 
pointed to by PREV ); a 
loop back to the BEGIN 
will occur. This is 
because chances are 
that this buffer is 
likely to be referenced 
again and therefore 
should not be overlayed 
with the new block data 
from disk. 


Set up for I . 


Stuff USE with the 
address of the next 
buffer to allocate. 


Set up for i§ . The top 
of the return stack 
contains the address of 
the buffer that is 
being allocated. 


Pick up the block 
number from the buffer 
being allocated. 


Test to see if the 
update bit is set. 
(Since the update bit 
is the MSB, when it is 
set, the word has a 
negative value.) 


LIT 

7FFFH 


.(BUFF2] 


"IF" the update flag 
was set, the true 
portion of the 
following IF statement 
writes the data 
contents of the buffer 
to disk. 


-^BUFF2) 

Branch if the update 
flag was not set. 

Get the address of the 
buffer being allocated, 
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R 


PREV 


R> 


2 + 


;s 



Again get the address 
of the buffer being 
allocated. 


PREV contains the 
address of the most 
recently referenced 
buffer. 


Make this newly 
allocated buffer also 
the most recently 
referenced buffer. 


Remove the address of 
this newly allocated 
buffer from the return 
stack. 


Skip over the block 
number and return the 
beginning address of 
the data portion of the 
buffer. 
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C! 


Cl ( byte \ address — ) 

Cl (pronounced "C-store") stores a byte (or "character"—hence "C"-store) from the top of the stack into the specified memory location. 
Word addressing computers may need further specification. 

1 is the word used to store 16-bit vaiues into memory. Qai has the opposite effect of C: . 

HOLD is an example of a word which uses Cl 

* At entry - The top of the parameter stack contains the 16-bit address specifying the location the byte is to be stored into. The 
second entry contains a 16-bit word. The low order 8-bits are stored into memory. The high order 8-bits are ignored. 

* At exit - No parameters. 

Cl is a low level code primitive. 

Refer to C{a) , and 1 . 

FORTH-79: The FORTH-79 equivalent for Cl is Cl . 



NEXT 
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C, 

C, ( single byte value — ) 

C, (pronounced "C-comma") stores the low order single byte, or character (hence, "C" comma) from the top of the parameter stack into 
the next available dictionary location and advances the dictionary pointer. 

The W ord 7 is used to store 16-bit values* 

* At entry - The low order 8-bits of the top parameter stack value contain the value to be stored into the dictionary. 

* At exit - No parameters. 

C, is a high level colon definition. 

Refer to DP . 

FORTH-79: C, is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". 

Definition: : C, ( byte value —) 

HERE Cl 1 ALLOT ; 


DOCOL 


HERE 


Cl 


1 


ALLOT 


;S 



Store the byte into 
dictionary. 


Aim Dictionary Pointer 
( DP ) past byte just 
stored. 
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C/L 


C/L ( — characters per editing line ) 

C/L (pronounced "C-slash-L") is a single precision CONSTANT value. This constant places the number of characters per editing line onto 
the top of the parameter stack. FORTH editing screens normally consist of 1024 (decimal) characters organized as 16 lines of 64 
characters. 

VLIST is an example of a word which uses C/L. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the signed 16-bit single precision value of the number of characters per 
editing line. 

FORTH-79: There is no FORTH-79 equivalent for C/L . 
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c@ 


C@ ( address — byte ) 

C(a) (pronounced "C-fetch") replaces an address on the top of the parameter stack with the 8-bit contents of that memory location. 
Note that (a) is used to fetch 16-bit values from memory. 

CREATE is an example of a word which uses Qa). 

* At entry - The top of the parameter stack contains the 16-bit address specifying the memory location from which the byte 
will be fetched. 

* At exit - The low order 8-bits of the top of the parameter stack contain the 8-bit contents of the specified memory 
address. The high order 8-bits of the top of the parameter stack contain zeros. 

Cfa) is a low level code primitive. 

Refer to (a) . 

FORTH-79: The FORTH-79 equivalent for C(a! is Qa) . 



HPUSH Push fetched byte onto 

stack. 


NEXT 
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CFA 


CFA ( Parameter Field Address — Code Field Address ) 

CFA (pronounced "C-F-A") converts a given Parameter Field Address ( PFA ) of a dictionary definition into its Code Field Address 
( CFA ). 

The structure of the header of a FORTH definition is: 

Name Field Variable length 

Link Field 2 byte address pointer 

Code Field 2 byte address pointer 

Parameter Field Variable length 

An example of the use of CFA can be found in the word (;CODE) . 

* At entry - The top of the parameter stack contains the 16-bit Parameter Field Address of a FORTH definition. 

* At exit - The top of the parameter stack contains the 16-bit Code Field Address of the specified FORTH definition. 

CFA is a high level colon definition. 

Refer to NFA , LFA , and PFA . 

FORTH-79: There is no FORTH-79 equivalent for CFA . A FORTH-79 program may not address into a definition's Code Field. 

Definition: : CFA (PFA--CFA) 

2 - ; 


DOCOL 


2 


;s 



Decrement the PFA by 2 
and are now aiming at 
the CFA . 
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CMOVE 


CMOVE ( source address\ destination address\ length — ) 

CMOVE (pronounced "C-move") is a character (byte) oriented word which moves a character string byte-by-byte from the source address 
to the destination proceeding towards high memory. Note that bytes are moved from the beginning of the string first; therefore the 
destination string cannot overlap the source string. (Some versions of FORTH use the word <CMOVE (backwards CMOVE ) to move 
strings which overlap in this manner.) 

Note, however, that if the destination address is 1 byte higher than the source address, CMOVE will have the effect of rippling the first 
byte throughout the specified length of memory. This ripple effect only works for read/write memory. It will not work for write-only 
memory (such as specialized video displays). This is because the byte to be moved must be read from memory. 

* At entry - The top of the parameter stack contains the unsigned 16-bit length of the string to move. The second entry 
contains the destination address and the third entry contains the source address. 

* At exit - No parameters. 

CMOVE is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for CMOVE is CMOVE . 



NEXT 
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COLD 

COLD ( - ) 


COLD is the "cold-start" routine for the FORTH system. The purpose of COLD is to initialize user variables to their startup values and 
then call ABORT . 

COLD may be executed from the terminal. Its effect is to remove all definitions except the basic FORTH vocabulary and reset the 
system. 

COLD performs seven basic tasks (8080 fig-FORTH version 1.1): 

1. Empties the buffers. 

2. Sets disk density. 

3. Initializes USE and PREV buffer pointers. 

4. Selects Drive 0 as the mass storage device. 

3. Disables the printer. 

6. Initializes the following USER variables: SO, R0, TIB, WIDTH, WARNING, FENCE, DP, and VOC-LINK. 

7. Calls ABORT . 

NOTE: The exact nature of COLD is installation dependent. 

* At entry - No parameters. 

* At exit - No parameters. 

COLD is a high level colon definition. 


FORTH-79: There is no FORTH-79 equivalent for COLD . 

Definition: : COLD ( --) ( 8080 Version 1.1 ) 

EMPTY-BUFFERS 0 DENSITY 1 FIRST USE 1 

0 EPRINT 1 ORG+12 UP 6 + 10 CMOVE 

ABORT ; 


DOCOL 


EMPTY- 

BUFFERS 


0 


DENSITY 



8080 fig-FORTH 
Version 1.1 


Initialize the disk 
buffers. 


Set up for 1 . 


DENSITY is a variable 
commonly used in 
fig-FORTH 

implementations which 
specifies whether 
single or double 
density disk drives are 
in use. 


In this case, 
initialize the system 
for single density 
drives. 


FIRST 


USE 


FIRST 


PREV 


FIRST PREV 1 DR0 
ORIG+C (9 FORTH+6 



Set up for . FIRST 
is the address of the 
"first" disk buffer. 
NOTE: The 8080 
Version 1.1 listing uses 
LIT BUF1 instead of the 
constant FIRST . 


Set up for ! . USE is 
used by buffer- 
allocation management 
(see BUFFER ) as a 
pointer to the next 
buffer to allocate (or 
"use"). 


Initialize USE with the 
address of the "first" 
buffer. 


Set up for 1 . FIRST 
is the address of the 
"first" disk buffer. 
NOTE: The 8080 Version 
1.1 listing uses LIT 
BUF1 instead of the 
constant FIRST . 


Set up for I . PREV 
is used by buffer¬ 
accessing management 
(see BLOCK ) as a 
pointer to the last 
buffer referenced. 
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LIT 

EPRINT 


LIT 

0RIG+12H 



Initialize PREV with 
the address of the 
"first" buffer. 


Initialize the system 
to use drive 0. 


Set up for I . 


EPRINT is a variable 
commonly used in 
fig-FORTH installations 
to denote the state of 
the printer. 


Disable the printer. 


Initialize all | 
necessary user 
variables. j 


Set up "origin" 
parameter for CMOVE 
ORIG + 12H is the 
beginning of a string 
of values used to 
initialize user 
variables. 


Set up for + . UP is 
the beginning of the 
user variable data 
area. Words located 
here are referenced by 
USER variables. 


Set up for + . The 
portion of the user 
area to be initialized 
is 6 bytes from the 
beginning. 


Set up "destination" 
parameter for CMOVE 


Set up "count" 
parameter for CMOVE . 
8 words are to be moved 
(i.e., 16 bytes). 


CMOVE 


LIT 

ORIG+OCH 


LIT 

FORTH+6 


ABORT 


Move the specified 
number of bytes from 
the specified memory 
origin location to 
the specified memory 
destination 
location. 


Initialize the data 
portion of the 
following USER 
variables: 


Place the literal 
value (in this case, 
the address) of 
ORIG + OCH onto the 
top of the parameter 
stack. 


Replace the address 
on the top of the 
parameter stack with 
the memory contents 
of that address. 


Place the literal 
value (in this case 
the address) of 
FORTH + 6 onto the 
top of the parameter 
stack. 


Store the specified 
value into the 
specified memory 
location. 


Initialize the 
parameter and return 
stacks. Issue a 
start up message. 
Input data from the 
terminal, i.e., 
Perform a warm 
start. 


(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 


□u initial pararn 

stack address 
R0 Initial return 

stack address 
TIB Terminal Input 

Buffer Addr 
WIDTH Width of 

Name Field 

WARNING Message dis¬ 
play control 
FENCE "Forget" 

Boundary 

DP Dictionary 

Pointer 

VOC-LINK Vocabulary 
Chaining 
Pointer 


Aim the FORTH 
vocabulary link pointer 
at the last (topmost) 
word in the FORTH 
vocabulary. 


Set up for (a) . This 
points to the address 
of the topmost word in 
the FORTH vocabulary 


Set up for 1 . Pick up 
the address of the last 
word in the FORTH 
vocabulary. 


Set up for I . This is 
the address of the 
"vocabulary link field" 
in the FORTH 
vocabulary definition. 


Initialize the FORTH 
vocabulary link 
pointer. 


ABORT - i.e.. 
a warm start. 


Perform! 


Bring the system 
rest of the way. 
















COMPILE 


COMPILE 

COMPILE TIME: (-) 
(Sequence 2) 

EXECUTION TIME: ( - ) 


COMPILE is a "form" of a compiler word and therefore has two sets of actions; an apparent compile time action (Sequence 2) and an 
execution time action (Sequence 3). 

COMPILE causes the CFA of the word immediately following COMPILE (in the input data stream) to be compiled into a definition. The 
CFA to be compiled is specified at Sequence 1 time when COMPILE is itself compiled into a compiler or defining word (i.e., the 
"parent"). 

COMPILE TIME -- How this "CFA specification" occurs is quite simple. When COMPILE is encountered in the input data stream, its CFA 
is automatically compiled by the Interpreter. When the word following CFA is encountered, (i.e., the "specified" word) its CFA is also 
automatically compiled into the dictionary immediately following COMPILE's CFA . Note that this is a normal compilation sequence. 
There is no correlation between COMPILE and the word "to be compiled" except that the CFA of the word "to be compiled" immediately 
follows the CFA of COMPILE . 

EXECUTION TIME — Since COMPILE performs compiling, it is important to keep in mind that COMPILE's execution time (Sequence 3) 
occurs at the word "to be compiled's" (i.e., the "child's") compilation time (Sequence 2). 

The specified CFA is actually compiled into a definition at Sequence 2 time when the compiler/defining (the "parent") word executes 
(creates a "child") thereby executing COMPILE . 

When COMPILE executes, the CFA it is to compile into the definition being compiled is physically located in the next Parameter Field 
location following COMPILE's CFA . This is also the location of the next CFA to be executed and therefore the address of this location 
has been placed onto the top of the return stack by DOCOL . 

COMPILE obtains this address from the return stack, uses it to fetch the specified CFA, then increments the address by 2 and returns it 
to the return stack. This skips over the "specified" CFA and will cause the location following the specified CFA to be executed when 
COMPILE finishes. 

An example of the use of COMPILE is the conditional branch word IF . The execution time procedure for IF is OBRANCH . This is 
specified within the source code for IF as COMPILE OBRANCH. At Sequence 1 when IF is compiled, the CFA's for COMPILE and 
OBRANCH are compiled into IF's definition. Later, during Sequence 2, when F is executed, the CFA for OBRANCH is compiled into the 
"child's" Parameter Field. 

This concept of specifing the name of the definition to be compiled at Sequence 1 but not actually compiling it into a definition until 
Sequence 2 is called "deferred compilation". 


COMPILE TIME (Sequence 2): 

* At entry - No parameters however COMPILE must be followed by the word desired to be compiled into the dicitionary. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - No parameters. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

? pronounced "HUH?" (0) — The word in question cannot be found in the dictionary. 

COMPILATION ONLY (11H) — This word may only be used within a colon definition. 

COMPILE is a high level colon definition. 

Refer to INTERPRET , and IF . 

FORTH-79: The FORTH-79 equivalent for COMPILE is COMPILE . 

Definition: : COMPILE ( —) ( execution time) 

/COMP >R DUP 2+ R> faj , ; 
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COMPILE TIME action of COMPILE (Sequence 2): ( — ) 

NOTE: Although COMPILE performs compilation, it has no compile time action itself. Instead, COMPILE relies upon the normal 
compiler mechanism of the Interpreter to do the following: 

1. The Interpreter must compile the CFA of COMPILE into the parent definition. 

2. The Interpreter must compile the CFA of the definition whose CFA is to be eventually compiled into the parent definition. 


Parameter Field of 
"Parent" Definition 
CFA of COMPILE 


CFA of Definitiun 
to be Compiled 
( FROG ). 


Input Data Stream 
to "Parent" Definition. 

. . . COM PILE FROG_ 

<D--' 



EXECUTION TIME action of COMPILE (Sequence 3): ( — ) 


DOCOL 


?COMP 


>R 


DUP 


2 + 


R> 



(a 


Note: This places the 
address of the word 
following COMPILE onto 
the return stack. 


If an error message is 
issued, a QUIT will be 
executed and 
compilation will stop 
here. 


Get the address of the 
word following 
COMPILE . 


Now have two addresses. 


Increment this address 
by 2. Now aiming at the 
next entry after the 
word to be compiled. 

This CFA is in the 
dictionary so it can be 
compiled; not so it can 
be executed. 


Put new return address 
back onto the top of 
the return stack. 


;s 



Set up for , . Using 
the remaining address 
on the parameter stack, 
pick up the contents of 
the "word to be 
compiled's" Code Field. 


Store the Code Field 
Address into the next 
available dicitionary 
position ( HERE). 
i.e., COMPILE it into 
the dictionary. 
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CONSTANT 


CONSTANT 

COMPILE TIME): ( value - ) 

(Sequence 2) 

EXECUTION TIME: ( - value ) 

ffipniiPnrA ^ 

x —~i--- - * 

CONSTANT is a defining word and therefore exhibits two different sets of actions; those actions at compile time and those at execution 
time. 

A CONSTANT in FORTH has the same effect as a constant in most other computer languages. That is, a memorv location containing a 

fixed value that can be referenced via a name. CONSTANT does differ from other languages in that it is active. When the constant 

name executed , the constsnt value is placed onto the top of the parameter stack. — 

The compile time action of CONSTANT is to define a named 16-bit constant in the form: 

n CONSTANT cccc 

where n is the constant's value and cccc is the value's assigned name (e.g., 26 CONSTANT MAX-LETTERS). 

The execution time action of CONSTANT , when the named constant is referenced, is to push this 16-bit value onto the too of the 
parameter stack. v 

It is possible to change the value of a RAM-based constant but this is extremely poor programming practice. VARIABLE should be used 
if the value must change. 

An example of the use of CONSTANT are the words LIMIT and FIRST . These words are used in +BUF . 


COMPILE TIME (Sequence 2): 

* At: entry - The top of the parameter stack contains the 16-bit single precision constant value. The constant's name must 
immediately follow CONSTANT in the input stream. 

* At exit - No parameters. 


EXECUTION TIME (Sequence 3): 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the previously defined 16-bit value. 
LIKELY ERROR MESSAGES: 


DICTIONARY FULL (2) — The dictionary has grown into the Terminal Input Buffer. 


DEFINITION NOT FINISHED (14H) — The position of the parameter stack pointer is not the same as it was when 
being compiled. Something is wrong with the definition. 


this definition started 


CONSTANT is a high level colon definition. 


Refer to VARIABLE , and +BUF . 


FORTH-79: The FORTH-79 equivalent for CONSTANT is CONSTANT . 


Definition: : CONSTANT ( value —) ( compile time ) 

CREATE SMUDGE , ;CODE 
Note: The assembly language execution time code follows the ;CODE . 
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COMPILE TIME action of CONSTANT: ( value — ) 
(Sequence 2) 


EXECUTION TIME action of CONSTANT : ( — value ) 
(Sequence 3) 


DOCOL 


CREATE 


SMUDGE 


(;CODE) 



NOTE: The Code Field 
Address will be aimed 
at the beginning of the 
Parameter Field. 


This "cancels" the 
previous SMUDGE done 
in the previous 
CREATE. 


This actually places 
the constant value into 
the Parameter Field of 
the word. 


(;CODE) places the 
address of the 
following dictionary 
entry into the CFA . 
Therefore, the run time 
code immediately 
follows this definition. 



NEXT 


NOTE: The execution time (Sequence 3) code for CONSTANT physically and immediately follows the ;CODE in the 8080 fig-FORTH 
Version 1.1. 










CONTEXT 


CONTEXT ( — data address ) 

CONTEXT is a user variable which contains a pointer to the vocabulary which is to be searched first. 

CONTEXT is set to point to a specific vocabulary by executing that vocabulary name. For example, FORTH causes CONTEXT to be 
aimed at the FORTH vocabulary. At system startup, CONTEXT is initialized to FORTH by ABORT which is called by COLD . Note that 
this means that any time an ABORT occurs CONTEXT wiii be aimed at the FORTH vocabulary. 

The use of CONTEXT is fully explained in the description of the word VOCABULARY . 

The user variable CONTEXT is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable CONTEXT . 

Refer to VOCABULARY , ABORT , and USER . 

FORTH-79: The FORTH-79 equivalent for CONTEXT is CONTEXT . 
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COUNT 


COUNT ( text string address — text address \ char count ) 

COUNT replaces the address of a text string with the byte length and byte address of the text string. The first byte of the text string 
must contain the string length. The text must begin at the second byte. ( WORD automatically provides this format.) 


BEFORE 

Top of stack points here- 


|41F1 R| ol d| 

^ _ 


AFTER 

Top of stack = 4 
2nd entry points here- 


1 4j F| Rio 


X 


COUNT is often used before I YPt 


." is an example of a word which uses COUNT. 

* At entry - The top of the parameter stack contains the address of the beginning of a text string (the length byte). This 
first byte of the string must contain the length of the text (not including the length byte itself). 

* At exit - The top of the parameter stack contains the length of the text string. The second entry contains the actual 
beginning text address. 

COUNT is a high level colon definition. 

Refer to TYPE . 

FORTH-79: The FORTH-79 equivalent for COUNT is COUNT . 

Definition: : COUNT ( text string address — text address\char count) 

DUP 1+ SWAP C® : 


DOCOL 


DUP 


1 + 


SWAP 


C(§ 


;S 



Duplicate length byte 
address for 1+ . 


Aim at the first 
character of the text 
string. 

Bring the length byte 
address to the top of 
the stack to set up for 
Cfa) . 


Put the text string 
length onto the top of 
the stack. 
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CR 


CR (-) 

CR (pronounced "carriage-return") is an installation dependent word which usually transmits a carriage return and a line feed to the 
selected output device. 

* At entry - No parameters. 

* At exit - No parameters. 

CR is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for CR is CR . 

8080 fig-FORTH 
Version 1.1 


NEXT 
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CREATE 


CREATE ( -) 

CREATE is a defining word used to "create" the header portion of a FORTH definition. It is used in the form: 


CREATE definition name 


CREATE builds a standard FORTH header. That is to say that it creates a Name Field, a Link Field, and a Code Held. Words that 
directly use CREATE are classified as being "defining words". 

The beginning and ending bytes of the Name Field have their high order bits set. The "smudge" bit in the Name Field is also set. The 
maximum number of characters saved in the Name Field is controlled by the value stored in the user variable WIDTH . 


Before creating a header, CREATE checks both the CONTEXT and CURRENT vocabularies to determine if the new definition name is 
unique. If it is not, the message "ISN'T UNIQUE" is issued. The definition header is created in either case. 

The Link Field is set to point to the last definition added to the vocabulary. The "current" vocabulary's "vocabulary pseudo link field" 
(not to be confused with the VOC-LINK field) is changed to point to the definition being "created". (See VOCABULARY .) 


The Code Field is set to point to the Parameter rieid which follows the header. Note that no Para; 


rjgK-j gpgoo je sllocstsd. 


: (colon) is an example of a word which uses CREATE . 


* At entry - No parameters. 

* At exit - No parameters. 

UK ELY ERROR MESSAGES: 

DICTIONARY FULL (2) — The dictionary has grown into the Terminal Input Buffer. 


CREATE is a high level colon definition. 

Refer to WIDTH , VOCABULARY , CURRENT , WARNING and :. 

FORTH-79: In FORTH-79 the word CREATE now has the same meaning as the fig-FORTH <BUILDS . Refer to FORTH-79 Standard. 


Definition: : CREATE ( —) ( 8080 Version 1.1 ) 

-FIND 

IF DROP NFA ID. 4 MESSAGE SPACE THEN 

HERE DUP Cfa) WIDTH fa) MIN 1+ ALLOT DUP AO TOGGLE 

HERE 1 - 80 TOGGLE LATEST , CURRENT 0 '. 

HERE 2+ , ; 



8080 fig-FORTH 
Version 1.1 


DOCOL 


-FIND 



8080 fig-FORTH 
Version 1.1 


Check for duplicate 
Jname and issue Error 
I Message 4 ("ISN'T 
UNIQUE") if needed. 


NOTE: Besides 
searching for a match, 
-FIND also causes the 
next input stream word 
to be moved (by WORD ) 
to HERE -- which is 
exactly where the 
character string needs 
to be to become the 
Name Field of the 
definition being 
created. 


Figure CREATE-1 
High Level Flow Chart of CREATE 
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DROP 


NFA 


ID. 


LIT 

4H 


MESSAGE 


SPACE 


THEN 





Branch if a match was 
not found. Else, the 
name of the definition 
being created is a 
duplicate of an already 
existing definition and 
Error Message 4 
("ISN'T UNIQUE") is 
issued. (No (ABORT) 
is issued). 



Drop the Name Field 
length left by -FIND . 


Set up for ID. . 
Convert the PFA 
(Parameter Field 
Address) left by -FIND 
into the NFA (Name 
Field Address) of the 
matching definition. 


Print the name of the 
duplicate definition. 


Set up for MESSAGE. 
Error Message 4 
("ISN'T UNIQUE"). 


Print "ISN'T UNIQUE" 
(or 4). 


Follow the message with 
a blank. 


HERE 


DUP 


C@ 


WIDTH 




MIN 


< 


This is the entry point 
from the false branch 
of the previous IF . 


If the definition being 
created was unique, 
control is passed 
directly here; else, 
"ISN'T UNIQUE" 
message was issued 
and control then 
passes here. 

Now "create" the 
definition header. 


ALLOT 


> 



Create the Name 
J Field. Set up to allow . 
I space in the dictionary! 
I for the Name Field. 


L_ 


The length byte (i.e., 
the beginning of the 
name of the definition 
being created) is 
pointed to by HERE . 


Set up for 1 . This NFA 
will later be stored 
into the "vocabulary 
link field" of the 
current vocabulary 
definition. 


Set up for MIN . Get 
the character count of 
the definition name. 


WIDTH contains a value 
from 1 to 31 which is 
used to determine how 
many bytes of a 
definition name are to 
be used in the Name 
Field. 


Set up for MIN . 


Set up for 1+ . MIN 
compares the actual 
length of the 
definition name with 
the maximum allowable 
name length and retains 
the lesser of the two. 
This value is then used 
to set the number of 
bytes in the Name 
Field. 


Set up for ALLOT . 

The number of bytes 
allocated for the Name 
Field must include one 
additonal byte for the 
Name Field length. 


This reserves the 
calculated number of 
bytes in the dictionary 
for the Name Field. If 
WIDTH was smaller than 
the actual length of 
the name, the remainder 
of the name will be 
truncated (overlayed) 
as the rest of the 
definition is created. 
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DUP 


LIT 

AOH 


TOGGLE 


HERE 


LIT 

80H 


TOGGLE 


LATEST 


Duplicate 
value on tl 
parameter 

the top 
ie 

stack. 



Place the literal 
value AOH onto the 
top of the parameter 
stack. 




Complement the 
specified memory 
location with the 
specified bit 
pattern. 


Place the address of 
the next available 
dictionary location 
onto the top of the 
parameter stack. 


^et Name Field bits^ 


Set up for TOGGLE . 
Duplicate the address 
of the beginning of the 
Name Field. 


Set up for TOGGLE . 
The AOH is composed of 
an 80H which is the 
"beginning of Name 
Field bit" and a 20H 
which is the smudge 


This "OR's" the bit 
mask into the length 
byte. 


Set up to eventually 
TOGGLE to "end of 
Name Field bit". NOTE: 
The previous ALLOT 
"allotted" space in the 
dictionary for the Name 
Field. The address 
returned by HERE now 
points to the first 
byte past the end of 
the Name Field. 


Place the c 
value 1 ont 
of the para 
stack. 

:onstant 
o the top 
meter 




Subtract the top 
stack entry from the 
second stack entry 
and replace the two 
values with their 
signed difference. 


the CURRENT 
vocabulary onto the 
top of the parameter 
stack. 


m IRRFMT 






Place the literal 
value 80H onto the 
top of the parameter 
stack. 



Exclusive-OR the 
byte at the 
specified address 
with the specified 
bit mask. 



Place the Name Field 
Address of the last 
definition added to 


Set up for - 


Back up one byte to aim 
at the last character 
in the Name Field. 


Set up for TOGGLE . 
The 80H bit is the "end 
of Name Field" flag. 


This "OR's" the 80H bit 
into the last Name 
Field character. 


Link the definition to 
the previous definition 1 
in the vocabulary 
chain. 


LATEST returns the 
address of the 
definition that this 
definition must be 
linked to. 


HERE 


2 + 


JS 


Store (compile) the 
16-bit value on the 
top of the parameter 
stack into the next 
available dictionary 
iocation. _ 


Place the address of 
the user variable 
CURRENT onto the top 
of the parameter 
stack. 


Place the address of 
the next available 
dictionary location 
onto the top of the 
parameter stack. 


(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


Replace the address 
on the top of the 
parameter stack with 
the memory contents 
of that address. 


1_ 

_1 

Store the s 
value into 
specified n 
location. 

pecified 

the 

nemory 


Increment the top 
parameter stack 
value by 2. 


Store (compile) the 
16-bit value on the 
top of the parameter 
stack into the next 
available dictionary 
location.__ 


This creates the Link 
Field for this 
definition (i.e., the 
Link Field is chained 
to the next higher 

L S am »r* kL 

UC I 11 i 1HUi I ill Cl no 

vocabulary). 

Link the "vocabulary 
link pointer" to the L 
definition being | 

created. j 

The value in CURRENT j 

nninfe fn hho 

"vocabulary link field" 
in the "current" 
vocabulary definition. 


Pick up the address of 
the "vocabulary link 
field." 


Store the previously 
duplicated NFA of this 
definition into the 
"vocabulary link field" 
(i.e., update the 
vocabulary pointer so 
that it now points to 
the latest definition 
appended to the 
vocabulary. _ 


< Create the Code Field. > 


This is the address of 
the Code Field ( CFA ). 


Adding 2 to the CFA 
points to the beginning 
of the Parameter Field. 


This creates the code 
field. The Code Field 
is left pointing to the 
Parameter Field. 
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CSP 


CSP ( — data address ) 

CSP (pronounced "C-S-P" for Compiler Stack Pointer) is a user variable which is used as a temporary storage location for the stack 
pointer position. 

Thjs is normally used as a compiler security check. A word such as : will execute 1CSP which stores the stack pointer position into CSP , 
° e 'r? re . c u on ? piImg a definition. Then, before the new definition is "un-smudged", ?CSP is executed. ?CSP compares the value stored in 
CSP with the current stack pointer and issues an error message if the two are not equal. 

The user variable CSP is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit -The top of the parameter stack contains the address of the user variable CSP . 

Refer to : , '.CSP , ?CSP , and USER . 

FORTH-79: There is no FORTH-79 equivalent for CSP . 
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CURRENT 


CURRENT ( — data address ) 

CURRENT is a user variable that contains a pointer to the vocabulary to which definitions are "currently" being appended to. 

The use of CURRENT is fully explained in the description of the word VOCABULARY . 

The user variable CURRENT is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

CURRENT is set to point to a specific vocabulary by executing the word DEFINITIONS , that copies the vocabulary pointer in CONTEXT 
into CURRENT . At system startup, CURRENT is initialized to FORTH by ABORT which is called by COLD . Note that this means any 
time an ABORT occurs, CURRENT will be aimed at the FORTH vocabulary. 

* At entry - No parameters. 


* At exit - The top of the parameter stack contains the address of the user variable CURRENT 


Refer to DEFINITIONS , VOCABULARY , ABORT , and USER . 


FORTH-79: The FORTH-79 equivalent for CURRENT is CURRENT . 
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D+ ( double \dotfcle — 32-bit sum) 

D+ (pronounce'] "D-p!us") adds the top two 32-bit signed values on the parameter stack and replaces them with their 32-bit signed sum. 

Note that generation of a carry goes unnoticed. 

( NUMBER ) is an example of a word which uses D+ . 

* At entry - The top and second words of the parameter stack contain a 32-bit signed double precision value with the signed, 
most significant portion on the top of the stack. The third and fourth stack entries contain the other 32-bit number to be 
added. 

* At exit - The top and second stack entries of the parameter stack contain a 32-bit signed double precision sum with the 
signed, most significant portion on the top of the stack. 

D+ is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for D+ is D+ . 



8080 fig-FORTH 
Version 1.1 


i.e., Aim at fourth 
entry on stack. 


Save IP on the stack. 


Uses memory to register 
add. 


HPUSH 

NEXT 


Push high order word of 
32-bit result. 














D + - 

D+- ( double \ angle — double ) 

D+- (pronounced "D-plus-minus") negates the sign of the double precision value in the second and third stack entries if the sign of the top 
single precision value is negative. The top value is then dropped. 

The following truth table describes the outcome of all possible combinations: 


SECOND ENTRY 

TOP OF STACK 

RESULT 

+D2 

+V1 

+D2 

+D2 

-VI 

-D2 

-D2 

+V1 

-D2 

-D2 

-VI 

+D2 


DABS is an example of a word that uses D+- . 

* At entry - The top of the parameter stack contains a signed 16-bit single precision value. The second stack entry contains 
the signed, high-order portion of a 32-bit double precision value. The third stack entry contains the low-order portion of 
this double precision value. 

* At exit - The single precision value is dropped. The 32-bit double precision value is on the top of the parameter stack with 
the signed high order portion on the top of the stack. The low order portion is in the second stack entry. 

D+- is a high level colon definition. 

FORTH-79: There is no FORTH-79 equivalent for D+- . 

Definition: : D+- ( double\single — double ) 

0< IF DMINUS THEN 


DOCOL 



(Run time portion of 
:) Save IP and 
start interpreting 
this definition. 


0 < 


F 


DMINUS 


THEN 


;s 


Replace the value on 
the top of the 
parameter stack with 
a true flag (1) if 
the value is less 
than 0 (negative); 
otherwise, replace 
the value with a 
false flag (0). 


Set up for F . Branch 
and do not negate the 
second value if the top 
value is positive. 






Negate (two's 
complement) the 

32-bit value on the 
top of the parameter 
stack. 

\ —- 


) " 


(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


The top of the stack 
was positive, so 
branch. 


Set the "second" stack 
value to minus. 


Entry point from "false 
portion" of previous 
IF . 
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D 


D. ( double — ) 

D. (pronounced "D-dot") performs a binary-to-ascii conversion (pictured numeric output) on the 32-bit signed double precision value on 
the top of the stack and prints the result on the output device followed by one space. 

The sign is only displayed if the value is negative. 

D. does not pad with blanks. Use D.R if a specific minimum field length is needed. 

The current value in BASE is used as the conversion radix. 

The pictured numeric output words <# , #S , SIGN , and //> are used to actually perform the conversion. These are located in D.R which 
is used by D. . 

* At entry - The top of the parameter stack contains a signed 32-bit double precision value to be converted and printed. 

* At exit - No parameters. 

D. is a high level colon definition. 

Refer to D.R . 

FORTH-79: The FORTH-79 equivalent for D. is D. . 

Definition: : D. ( double —) 

0 D.R ; 


DOCOL 


0 


D.R 


;s 



Set up for D.R . Put 
field width onto the 
top of the stack. 

(Note: D.R does not 
truncate. The value 
will always be 
completely printed, 
even if it is larger 
than the field width. 

In this case, anything 
is larger than the 
field width. This is a 
programming "trick" to 
prevent padding blanks 
from being appended to 
the output.) 
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D.R 


D.R ( double \ field width — ) 

D.R (pronounced "D-dot-R") performs a binary-to-ascii conversion (pictured numeric ouput) on a signed 32-bit double precision value and 
prints the result in a right justified field whose minimum width is specified by the value on the top of the stack, e.g., If a field length of 
10 is specified and only 3 characters are printed the remainder of the field will be left padded with 7 blanks (6) For example: 

123 0 10 D.R results in B66666E6123 

Note, however, that D.R is rather "stupid". If a field length of 3 characters is specified but the input value is large enough to print 10 
characters all ten characters will be printed. i.e., D.R does not truncate values larger than the field width. For example: 

123456 0 3 D.R results in 123456 


No trailing blank is printed. Use D. if a minimum width field is not needed. 
The current value in BASE is used as the conversion radix. 


The sign is only displayed if the value is negative. 

The basis of D.R is it . D.R is a good example of how to set up parameters for signed pictured numeric output. 


D. is an example of a word which uses D.R . 

* At entry - The top of the parameter stack contains the signed 16-bit value which specifies the field width of the converted 
ascii string. The second and third stack entries contain a signed 32-bit double precision value to be converted and printed 
with the signed high order portion in the second stack entry and the low order portion in the third stack entry. 

* At exit - No parameters. 


D.R is a high level colon definition. 
Refer to <# , it , SIGN , itS , and it> . 


FORTH-79: The FORTH-79 equivalent for D.R is D.R . 

Definition: : D.R ( double\field width —) 

5R SWAP OVER DABS Kit itS SIGN //5 R5 


DOCOL 


>R 


SWAP 


OVER 


DABS 



Temporarily save field 
width. 


Set up for OVER . Put 
high order signed 
portion of the value 
into the second entry. 


Set up for SIGN . This 
puts the double 
precision value back 
into the correct format 
while leaving the 
16-bit signed portion 
in the third entry for 
SIGN to use. _ 


Set up for pictured 
numeric conversion by 
getting rid of the 
sign. 


Kit 

US 


SIGN 


if> 


R> 


OVER 


OVER SPACES TYPE 




Retrieve field length. 


Set up for - . Get the 
converted text length 
so can subtract it from 
specified field length. 
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SPACES 


TYPE 


;s 



Set up for SPACES . 
Field width minus text 
length equals number of 
bytes to pad with 
spaces. 
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DABS 


DABS ( signed double value — absolute double value ) 

DABS (pronounced "D-ABS" for Double ABSolute) replaces a signed 32-bit double precision number with its absolute value. That is, 
negative values are made positive. 

M/ is an example of a word which uses DABS . 

* At entry - The top of the parameter stack contains the signed high order signed portion of a 32-bit double precision 
value. The second stack entry contains the low order portion of the value. 

* At exit - The top of the parameter stack contains the high order portion of the absolute value of the original number. The 
second stack entry contains the low order portion of the value. 

DABS is a high level colon definition. 

Refer to D+- . 

FGRTH-79: The FORTH-79 equivalent for DABS is DABS , 

Definition: : DABS ( signed double - absolute double ) 

DUP D+- : 


DOCOL 


DUP 


D+- 


;S 



Set up for D+- . 
Duplicate the sign 
portion of the original 
value. 


If original value is 
positive, nothing 
happens (as it is 
already absolute). If 
original value is 
negative, the sign 
portion is negated, 
making it positive, 
i.e., absolute. 
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DECIMAL 

DECIMAL ( - ) 

DECIMAL sets the user variable BASE to 10 (decimal). This causes all numeric input and output conversions to be performed in decimal 
(base 10). 

Note that this is not an IMMEDIATE word. 

* At entry - No parameters. 

* At exit - No parameters. 

DECIMAL is a high level colon definition. 

Refer to (NUMBER) , and BASE . 

FORTH-79: The EORTH-79 equivalent for DECIMAL is DECIMAL . 

Definition: : DECIMAL ( --) 

0A BASE 1 ; 


DOCOL 


LIT 

OAH 


BASE 


;s 



Store the literal value 
OAH (10 decimal) into 
BASE . 
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DEFINITIONS ( - ) 


DEFINITIONS 


DEFINITIONS is used to specify the vocabulary into which new "definitions" are to be added (hence the name "DEFINITIONS"). 


Vocabularies in FORTH serve to limit the scope of a name; therefore, it is necessary to be able to specify which vocabulary a given name 
is to be appended. The user variable CURRENT points to the vocabulary which "currently" will have new definitions appended to it. 
DEFINITIONS copies the contents of the user variable CONTEXT into CURRENT. CONTEXT points to the vocabulary which is to be 
en performing dictionary searches and is set to point to a specific vocabulary by stating (i.e., executing) the vocabulary 


--FI 

ocdiuicu nid 


For example: Suppose a vocabulary named CAMERA has previously been created via the word VOCABULARY. Executing CAMERA sets 
CONTEXT to point to CAMERA (i.e, CAMERA will be searched first). Executing DEFINITIONS then copies CONTEXT into CURRENT 
(i.e, new definitions will now be added to CAMERA). 


Normal usage would be in the form: 


CAMERA DEFINITIONS 


This not only causes definitions to be added to CAMERA but also helps produce highly readable, understandable l-OKTH listings 
describing exactly what is happening. 

CREATE is the word which actually uses the data in CURRENT to append a new definition to a vocabulary. Refer to VOCABULARY for 
a more extensive explanation of vocabularies and the words which support them. 

* At entry - No parameters but the user variable CONTEXT must contain a pointer to the vocabulary to which new 
definitions are to be added. 

* At exit - No parameters. 


DEFINITIONS is a high level colon definition. 

Refer to VOCABULARY , CURRENT , CONTEXT , and CREATE . 

FORTH-79: The FORTH-79 equivalent for DEFINITIONS is DEFINITIONS . 

Definition: : DEFINITIONS (-) 

CONTEXT ® CURRENT '. ; 


DOCOL 


CONTEXT 


§ 


CURRENT 



Set up for (a . 
CONTEXT contains a 
pointer which points to 
the Vocabulary Link 
Field of the vocabulary 
to be searched first. 


Fetch the pointer from 
CONTEXT. 


CURRENT contains a 
pointer which points to 
the Vocabulary Link 
Field of the vocabulary 
into which definitions 
are to be added. 


;s 



Make CURRENT equal 
to CONTEXT , i.e., 
definitions will now be 
appended to the 
vocabulary n ointed to 
by CONTEXT . (The 
vocabulary which was 
pointed to by CONTEXT 
when DEFINITIONS was 
executed.) 
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DIGIT 


In Range - ( char \ base — binary digit \ true flag ) 

Out of Range - ( char \ base — false flag ) 

DIGIT converts an ascii character into its binary equivalent using the specified base value. Either the binary "digit" and a true flag are 
returned or just a false flag is returned depending upon DIGIT's success. 

Validity checking is performed such that a character whose original value is less than 30H (i.e., less than ascii "0") or between 3AH and 
40H inclusive (greater than ascii "9" but less than ascii "A") is automatically invalid. After conversion from ascii to binary, any "digit" 
larger than the specified base is also invalid. 

There is no ascii upper range validity test. The character may be whatever scale the specified base allows. 

DIGIT works by first converting the ascii character to a binary value by stripping the ascii offset (30H) from the character. Then validity 
checking is performed and finally the value is tested to ensure it is within the maximum base range. 

(NUMBER) is an example of a word which uses DIGIT . 

* At entry - The top of the parameter stack contains an unsigned 16-bit single precision value specifying the base value. 

The second stack entry contains an ascii character to be converted to a digit. 

* At exit (digit within range) - The top of the parameter stack contains a "true" boolean truth flag. The second stack entry 
contains the binary "digit". 

* At exit (out of range) - The top of the parameter stack contains a "false" boolean truth flag. No "digit" is returned. 

DIGIT is a low level code primitive. 

Refer to (NUMBER) . 

FORTH-79: There is no FORTH-79 equivalent for DIGIT . 


( DIGIT ) 


8080 fig-FORTH 
Version 1.1 



{ Test if character is in 
the range of ascii 0 to 
ascii 9 inclusive. 1 


Subtracting 30H from 
the character strips 
the value of its ascii 
offset, (e.g., A digit 
value of ascii 2 is 
32H, subtracting 30H 
leaves 2H — the true 
digit value.) 



- DIG 12) 

Branch if subtracting 
30H resulted in a 
negative value. The 
character was less than 
ascii "0". 

-^ (digii) 

Branch if the character 
(now a digit) is within 
the range of 0-9, 




Subtract 7 from 
character value. 




Character is not 0-9 so 
now determine if it is l 
greater than or equal f 
to ascii A. j 


NOTE: In ascii, valid 
characters range from 
30H to 39H and 41H 
up. Subtracting 7 from 
the value "skips" over 
the gap between 39H 
and 41H. 



^TdIGI2) 


\DIGIi/- 


If the digit value went 
negative after 
subtracting 7, the 
character fell in the 
range between 39H and 
41H. 


Character is within the 
valid ascii range. Now 
determine if it is 
within the maximum 
base range. 


^ (pIGk) 
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Set truth flag in H 
to true. 






r-\r>i I Cl_1 DneK rlinif uqIiip nntn 

uruji i » 1 - 


stack. 

HPUSH Push truth flag onto 

stack. 

NEXT 



HPUSH Push truth flag onto 


stack. 

NEXT 
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DLITERAL 


DLITERAL 

COMPILE TIME: (double-) 

(Sequence 2) 

EXECUTION TIME: (-double) 

(Sequence 3) 

^LITERAL is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution 
time. 

DLITERAL has no effect (and does not signal an error) if not executed within a colon definition. 

The compile time action (Sequence 2) of DLITERAL is to compile a dynamically calculated 32-bit value into a definition. The end result 
of this compile action is the same as using LIT twice. The heart of DLITERAL is LITERAL, which in turn compiles LIT into the 
definition being compiled. The INTERPRETER compiles LIT into a definition "automatically" upon encountering a 16-bit numeric value 
in the input stream. However, if this numeric value is calculated dynamically during compilation, it will not exist in the input stream and 
therefore some other method must be used to compile LIT and the value into the dictionary. This is done by using the word LITERAL. 

Since DLITERAL is concerned with a double precision value, LITERAL is used twice. 

An example of the use of DLITERALwould be in dynamically calculating a maximum limit value to be used as a parameter. This 
calculation will be performed only once, at compile time, instead of each time the parameter is used. The definition would look like this: 

: xxx [ //-OF-ENTRIES 2(a) //-OF-PARMS 2(3 D+ ] DLITERAL DOIT ; 

[ stops compilation, //-OF-ENTRIES and //-OF-PARMS contain double precision values which are fetched and then added together to 
form the double precision limit value which is left on the stack. ] resumes compilation and DLITERAL compiles the 32-bit limit into the 
definition. 

The execution time action of DLITERAL is that of LIT . That is, upon execution of each LIT , the compiled 16-bit value is placed onto 
the top of the parameter stack. NOTE that DLITERAL is an IMMEDIATE word. This means that its precedence bit is set, and it will 
therefore execute at compile time. 

COMPILE TIME (Sequence 2h 

* At entry - The top of the parameter stack contains the signed high order word of a 32-bit double precision value. The 
second stack entry contains the low order portion of the value. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the signed high order word of a 32-bit double precision value previously 
compiled into the dictionary. The second stack entry contains the low order portion of the value previously compiled into 
the dictionary. 

DLITERAL is a high level colon definition. 


Refer to LITERAL , LIT , [ , ] , and INTERPRET . 


FORTH-79: 

There is no FORTH-79 

equivalent for DLITERAL . 



Definition: 

: DLITERAL 

STATE fa) 

( double — ) ( compile time ) 

IF SWAP LITERAL LITERAL 

THEN ; 

: IMMEDIATE 
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COMPILE TIME action of DUTERAL (Sequence 2)z ( double — ) 


DOCOL 


STATE 




IF 


SWAP 



At execution of 
□LITERAL, compute the 
low order portion of 
the 32-bit value. 


At execution of 
DLITERAL, compute the 
high order portion of 
the 32-bit value. 


Entry point from the 
false branch of the 
previous IF . 

i.e., Was not compiling 
so branch here and 
exit. 


DLITERAL is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


EXECUTION TIME action of DLITERAL (Sequence 3): ( — double ) 


LIT 

Compiled 

Value 


LIT 

Compiled 

Value 


Place the 
compiled \ 
the top of 
parameter 

iteral 
alue onto 
the 
stack. 



Place the 
compiled 
the top of 
parameter 

literal 
/alue onto 
the 
stack. 

r 


Place the low order 
portion of the 32-bit 
value onto the top of 
the parameter stack. 


Place the high order 
portion of the 32-bit 
value onto the top of 
the parameter stack. 
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DMINUS 

DMINUS ( double — negative double ) 

DMINUS (pronounced "D-minus" for Double MINUS) replaces the 32-bit signed value on the top of the parameter stack with its two's 
complement. 

* At entry - The top and second words of the parameter stack contain a signed 32-bit double precision value with the signed, 
most significant portion on the top of the stack. 

* At exit - The top and second entries of the parameter stack contain the two's complement of the given value with the 
signed, most significant portion on the top of the stack. 

DMINUS is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for DMINUS is DNEGATE . 



HPUSH Push high order 16 bits 

of complemented word. 


NEXT 
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DO 


DO 


COMPILE TIME: ( — loop address \ 3 ) 

(Sequence 2) 

EXECUTION TIME: ( Limit\ Index - ) 

(Sequence 3) 

DO is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution time. 

DO is used to mark the beginning of a fixed repetition loop structure. This is identical in purpose to the FORTRAN DO and the BASIC 
FOR statements. DO is used to create a DO-LOOP in conjunction with LOOP or +LOOP in the form: 

DO "loop body" LOOP 

DO "loop body" (Increment Value on stack) +LOOP 


The compile time action (Sequence 2) of DO is to compile (DO) into the definition and also to leave the entry point address of the next 
definition following (DO) on the parameter stack (i.e., the beginning address of the "loop body" portion of the loop.) This address is then 
used at compile time by LOOP or +LOOP to generate a branch offset. To provide compiler security, the vaiue 3 is placed on the top of 
the parameter stack so that LOOP or +LOOP can check for it. This provides a somewhat secure (but not foolproof) method of checking 
for un-paired DO's and LOOP's. 


The apparent execution time action (Sequence 3) of DO is actually performed by (DO) . This action is to remove the Index and Limit 
values from the parameter stack and place them onto the return stack to be used as inputs to LOOP or +LOOP . The Index (also referred 
to as Initial) value is incremented (or decremented) and compared with the Limit by LOOP or +LOOP each pass through the DO-LOOP . 


The loop Index is accessible within the DO-LOOP structure by using the word I . 

A " DO - LOOP " structure may be used only within a colon definition. 

Refer to (DO) and I for a more detailed explanation of the execution time behavior of DO . 

Note that DO is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 
INDEX is an example of a word which uses DO . 

COMPILE TIME (Sequence 2): 


* At entry - No parameters. 

* At exit - The top of the parameter stack contains the 16-bit single precision value 3. This value is checked by LOOP or 
+LOOP to provide compiler security. The second stack entry contains a 16-bit address pointing to the first definition to 
be executed as the "loop body" portion of the DO-LOOP structure. 

EXECUTION TIME (Sequence 3): 

* At entry - The top of the parameter stack contains the 16-bit signed Index value. The second stack entry contains the 
16-bit signed Limit value. 

* At exit - No parameters on the parameter stack; however, the return stack now has the Index value on the top of its stack, 
and the Limit value as the second entry on its stack. 


LIKELY ERROR MESSAGES: 

COMPILATION ONLY (11H) — This word may only be used within a colon definition. 
DO is a high level colon definition. 

Refer to LOOP , (LOOP) , +LOOP , (+LOOP) , (DO) , and I. 

FORTH-79: The FORTH-79 equivalent for DO is DO . 

Definition: : DO ( — loop address\ 3 ) ( compile time )_ 

k . COMPILE (DO) HERE 3 ; IMMEDIATE 
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COMPILE TIME action of DO (Sequence 2): ( — loop address \ 3 ) 


DOCOL 


COMPILE 


(DO) 


HERE 


3 


;S 


IMMEDIATE 


© 



This puts (DO) into the 
definition being 
compiled. 


(DO) is compiled into 
the definition during 
Sequence 2. 


The address of the 
first word of the group 
of words to be 
repeatedly executed 
inside of the loop is 
put on the stack so 
LOOP or +LOOP can use 
it. 

LOOP or +LOOP expect 
a 3 to be on the top of 
the stack. 


DO is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


EXECUTION TIME action of DO (Sequence 3): ( Limit value \ Index value — ) 


Refer to (DO) for the EXECUTION TIME action of DO . 
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DOES> 


DOES> 


DEFINITION TIME: (-) 

(Sequence 1) 

EXECUTION TIME: ( second Parameter Field Address — ) 

(Sequence 2) 

DOES> (pronounced "does") is a defining word and therefore exhibits two different sets of actions; those actions at definition time and 
those at execution time. 

DOES> is a Sequence 1 defining word that is used to create Sequence 2 defining words. DOES> is normally used in conjunction with 
<BUILDS to create defining words ("parents") which in tum create other words ("children"). 

An overall explanation including examples of the use of <BUILDS and DOES> is included in the description of <BUILDS . 

When creating a defining word (at Sequence 1), DOES> acts as a dividing line between the high level words that will create the "child" (at 
Sequence 2) and the high level words that are the "child's" run time procedure (at the "child's" Sequence 3). 

;CODE is used to create code level run time procedures. See Figure DOES>-l. 

The compile time action of DOES> is to overlay the "child" definition's Code Field with the address of the execution time code for 
DOES> . It also overlays the first Parameter Field location with the address of the definition following DOES> in the "parent" 
definition. This is the address of the "child's" first execution time procedure. When words that are then created with this defining word 
execute, the run time code of DOES> transfers control to the procedure following DOES> . (Refer to Figure DOES>-2.) 



Figure DOES>-l 

Compile Time Action of <BUILDS and DOES> 
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'PARENT" 


"CHILD" 



DODOES causes the run time procedure in the "parent" defining word to be executed when the "child" executes. 
The "child's" execution procedure that resides in the "parent" is executed during Sequence 3. 

Figure DOES>-2 

Execution Time Action of DOES> 


The execution time portion of DOES> is DODOES . This code performs two primary functions: 

1. It places the address of the "child's" Parameter Field (actually the second entry in the Parameter Field) onto the top of the 
parameter stack so it will be available for the run time program. 

2. It nests the return address of the "child" definition being executed and transfers control to the "child's" run time procedure 
(which is physically defined in the "parent" defining word definition). 

Note that many "children" can be created via a single "parent" defining word and all of the "children" reference the same execution time 
(Sequence 3) procedure located within the "parent" definition. 


In high level terms, the action of DOES> can be symbolically described as follows: 

IP@ RP(a) 1 Push IP onto the return stack, i.e., Nest the address of the next word to be executed so the system can return after 
executing the run time procedure. 

-2 RP +1 Increment the return stack pointer to point at the next available return stack location. 

W(3 2+ IP! W is now aiming at the Code Field of the "child" definition. Increment it by 2 so that W points to the pointer that 

aims at the run time procedure. 

NEXT Execute the procedure W is indirectly pointing to. 

DOES> may only be used within a colon ( :) definition. 

VOCABULARY is an example of a word which uses DOES> . 


DEFINITION TIME: 

* At entry - No parameters. 

* At exit -No parameters. 

EXECUTION TIME (Sequence 3 execution time of the "child"): 

* At entry - The top of the parameter stack contains the 16-bit address of the second Parameter Field entry in the "child's" 
definition. (Because the first Parameter Field entry was filled in by DOES> at compile time (Sequence 2), the second 
entry is the first location available to the definition.) 

* At exit - No parameters. 
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LIKELY ERROR MESSAGES: 

DEFINITION NOT FINISHED (14H) -- The position of the parameter stack pointer is not the same as it was when this definition started 
being compiled. Something is wrong with the definition. 

DOES> is a high level colon definition. 

Refer to <BUILDS , ;CODE , and NEXT . 

FORTH-79: The FORTH-79 equivalent for DOES> is DOES> . 

Definition: : DOES> ( -) ( compile time) 

R> LATEST PFA 1 ;CODE 

Note: the assembly language execution time code follows the ;CODE . 

Note that the fig-FORTH Model version of DOES> uses the first word of the Parameter Field as a pointer to the execution time 
(Sequence 3) procedure. (This sometimes causes problems because PFA returns the true PFA, while the "definition's" Parameter Field 
actually begins one word later.) This problem is solved in FORTH-79. FORTH-79 DOES> does not utilize the first Parameter Field 
location. Also note that in FORTH-79, CREATE is paired with DOES> instead of <BUILDS . 


DEFINITION TIME action of DOES> : ( - ) 


DOCOL 


R> 


LATEST 


PFA 



NOTE: It must be 
remembered that DOES> 
is a defining word. 

When DOES> is 
executed, the top of the 
return stack contains 
the address of the word 
following DOES> . The 
words following DOES> 
are to be executed when 
the word created by 
DOES> is executed. 
Therefore, their 
beginning address must 
be obtained via the R> . 


This gives the address 
of the definition 
currently being created 
by DOES> . 


Set up for I . The 
address of the 
execution time code for 
the definition being 
created by DOES> 
(obtained via the above 
R> ) must be stored 
into the first 
Parameter Field. 


Store the address of 
the definitions to 
execute (when the word 
being created is 
executed) into that 
word's first Parameter 
Field location. 


(;CODE) 


Run time portion of 
;CODE . Rewrite the 
CFA of the word 
being created to 
point to the code 
which follows. 


<BUILDS filled the Code 
Field of the word being 
created with the 
address of the run time 
code for CONSTANT . 
(;CODE) now overlays 
that address with the 
address of the run time 
code for DOES> . 

Note that at compile 
time (;CODE) eventually 
performs the same 
action as ;S . 


EXECUTION TIME action of DOES> : ( addr — ) 

Note: This is a very machine dependent routine. The following is 
the S08Q fig-FORTH version 1,1 routine. 



<BUILDS-DOES> is used 
in a compiling word. 
That compiling word is 
then used to create a 
new definition. (e.g., 
<BUILDS-DOES> creates 
VOCABULARY, 
VOCABULARY then 
creates FORTH .) 


The following execution 
time code for DOES> is 
executed when the 
definition created by 
the compiling word 
(e.g., FORTH) 
executes. 

NOTE: Register usage 
in the 8080 fig-FORTH 
Version 1.1 is: 

BC = IP 

DE = W 

HL = Work Register 
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Push IP (which is 
currently pointing at 
the next definition to 
interpret) onto the 
return stack. NOTE: 
This portion of code is 
identical to the "PUSH 
IP" code in DOCOL . 



Pick up the return 
stack pointer. 

Aim at the next 
available byte in the 
return stack. 


Move the high order 
portion of IP to the 
return stack. 


Aim at the next 
available byte in the 
return stack. 


Move the low order 
portion of IP to the 
return stack. 


Store the return stack 
pointer. 

Aim W at the Parameter 
Field. NOTE: DE was 
already incremented one 
byte by NEXT . Also 
note that W points to 
the Code Field of the 
word being executed. 
Incrementing W by two 
aims W at the 
Parameter Field. 


MOV C,M 



Move the low order 
address of the run time 
code for this word into 
IP . 


Aim at the next 
Parameter Field byte. 


Move the high order 
address of the run time 
code for this word into 
IP . 


Aim at the next 
Parameter Field byte. 
NOTE: This increment 
is important because 
part of the run time 
action of DOES> is to 
place the address of the 
"Parameter Field" of 
the definition being 
executed onto the top 
of the parameter stack. 


HPUSH HPUSH pushes HL (the 

address of the first 
usable Parameter Field 
location) onto the 
stack. 


NEXT NEXT then transfers 

control to the run time 
code for the definition 
being executed. 


< 


The Code Field of a 
word created with 
DOES> contains the run 
time code for DOES> . 
(i.e., The code being 
explained right now.) 

The compile time action 
of DOES> is to put the 
run time code address 
for the word being 
created in the first 
Parameter Field 
location. W has been 
incremented to aim at 
the address in the 
Parameter Field. Now 
put this code address 
into IP . The following 
code differs from 
DOCOL . XCHG put 
the Parameter Field 
Address into HL so that 
the code address in the 
Parameter Field can be 
moved via HL from 
memory to BC 
(remember BC is the IP 
register). 
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DP ( — data address ) 

DP (pronounced "D-P" for Dictionary Pointer) is a user variable that contains an address pointer to the next available dictionary 
location. It is initialized during system startup by COLD with data from the origin parameter area. 

The word HERE places the contents of DP onto the top of the parameter stack. The words ALLOT and FORGET alter the contents of 
DP . 

The user variable DP is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. Note that the word DP is not always a user variable. The physical location of DP is installation 
dependent (i.e., memory, a register, etc.). 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable DP . 

Refer to COLD , HERE , ALLOT , FORGET , and USER . 

FORTH-79; There is no FORTH-79 equivalent for DP . 
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DPL 


DPL ( — data address ) 

DPL (pronounced "D-P-L" for Decimal Point Location) is a user variable that re Beets the number of digits found to the right of a decimal 
point when converting a numeric character string into a numeric value. (Actually, it is relative to the last decimal point encountered.) 
The words NUMBER and (NUMBER) perform this conversion. If a decimal point is not encountered, NUMBER leaves a -1 in DPL . 

INTERPRET uses the contents of DPL to determine if a numeric value is to be treated as single precision (i»e», DPL contained -1 so no 
decimal point was encountered) or double precision (i.e., DPL did not contain -1 so a decimal point was encountered). Although 
INTERPRET uses a decimal point only for purposes of determining precision, this does not mean that an application cannot use the value 
stored in DPL to process the decimal point location. 

The user variable DPL is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable DPL . 

Refer to NUMBER , (NUMBER) , INTERPRET , and USER . 

FORTH-79: DPL is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". Note that DPL as 
described in the Reference Word Set is used for numeric output, not input. 
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DPUSH 


DPUSH ( - value ) 

DPUSH is strictly an 8080 fig-FORTH Version 1.1 inner interpreter routine entry point. 

Entry at this entry point causes the 16-bit contents of the DE register pair to be pushed onto the top of the parameter stack. Then the 
contents of the HL register pair is also pushed onto the top of the parameter stack then NEXT is executed. 

Refer to NEXT . 
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DRO DR1 

DRO ( - ) 

DR1 (-) 


nrScrr d F ° RTH mass f stora 9 e dev «ce selection words. These words store a block number offset into the user variable 

um- bh I , so that the programmer can reference a selected device as if the block numbers for that device begin with block zero. 

All FORTH mass storage I/O is virtual I/O. That is, desired information is referenced via block numbers, which to the programmer, are 
synonymous to the memory address of the desired data. The type of mass storage, the hardware addresses, and the media are normally 
transparent to the programmer. 7 

Each storage device on the system has a unique range of block numbers assigned to it. This allows device selection to be based solely 
throughTm™ r ranq6 ’ exam P le ’ Disk Drive 1 -ay contain blocks 0 through 799; while Disk Drive 2 may contain blocks 800 

a ? d i r <n Sir ? d °-T 3 SUgh r^ however * For instance, it is difficult to remember that certain data on a diskette 

resides at block 160 when the diskette in Drive 1; but the same data resides at block 960 when the diskette is in Drive 2. 

BLOCK solves this problem through the use of OFFSET . Immediately upon entry, the contents of OFFSET is added to the desired block 
Fvn^if Hr drive selection by previously setting (i.e., biasing) OFFSET to the starting block number of the selected 

drive. . Explicit drive selection may be performed by ensuring that OFFSET contains the value 0 before calling BLOCK . 

Je, e ireHT^ f S'? to «« th e user variable OFFSET with a bias value equal to the starting block number of the 

desired device. That way (for identical devices) a particular block of data can always be referenced via the same block number. 

Sel ^ ti0n ” ords are not limited to DRO and DR1 . Another common, but not standard, selection word is MTO which is 
used to select a tape drive. Device selection words are obviously installation dependent. 

* At entry - No parameters. 

* At exit - No parameters. 

DRO and DR1 are high level colon definitions. 

Refer to BLOCK , R/W , and OFFSET . 

FORTH-79: There is no FORTH-79 equivalent for DRO or DR1 . 

Definition: : DRO ( —) 

DRO-BEGBLK// OFFSET 1 ; 


DOCOL 


DRO- 

BEGBLK// 


OFFSET 


;s 
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Set up for 1 . For 
this example, the 
starting block number 
of Drive 0 is placed 
onto the stack. This 
constant would be 
defined as 
600 CONSTANT 
DRO-BEGBLK// 

Set up for I . 


Initialize OFFSET to 
the beginning block 
number of the desired 
device. 








DROP 


DROP ( value to be (topped — ) 

DROP discards the 16-bit value presently on the top of the parameter stack. 


DROP is commonly usea to aiseara 


_ _X._ £ -4-U~ hafnrp oviflnn Q WfipH Of nPOPfidU^G- 

parameters irum uiic ouaurv «wic v aiwm.^ « — — r-- 


DROP . 


#> is an example of a word which uses 


* At entry - The top of the parameter stack contains the 16 bit value to be discarded. 

* At exit - This value has been discarded (dropped). 

DROP is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for DROP is DROP . 



-8080 fig-FORTH 

Version 1.1 

Pop top of stack. 






NEXT Do nothing with value 

just popped. i.e., Drop 
it. 
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DUP 


DUP ( value 1 — value 1 \ value 1 ) 

DUP (pronounced "dupe") duplicates the 16-bit value presently on the top of the parameter stack. 

SftTr l L^n^rnZ°A m ?° n[y If.?' d W ° rd ; *? USUally USed t0 make 3 copy of an input Parameter so the original value will still be available 

after an intermediate word "uses up" the input parameter. 

COUNT is an example of a word which uses DUP . 


* At entry - The top of the parameter stack contains the 16-bit value to be duplicated. 

* At exit - The first and second 16-bit stack values are equal. 

DUP is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for DUP is DUP . 



again, i.e., Duplicate 
it. 


NEXT 
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ELSE 


COMPILE TIME (Sequence 2): ( offset address \ 2 — offset address \2 ) 

EXECUTION TIME (Sequence 3): ( — ) 

ELSE is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution time. 

ELSE is used as the beginning of the "false portion" of an IF structure in the form: 

IF "True Portion" ELSE "False Portion" THEN 

. . » |.k D n/\cp ai TF-THEN-ELSE structure.) The use of ELSE in this type of structure is optional. If 

ELSE te omitted, ‘a faTJboolean input causes control to simply branch to the word immeclbtely ,ollowin9 *•*> THEN ' When used ’ ELSE 
must be located within an F-ELSE-THEN structure. ( END IF may be used in place of THEN .) 

An F-ELSE-THEN structure must be used within a colon definition. 

location address is then placed on the parameter stack so that it m ® y *1 f! ^ j HEN jf the q_SE is left out of the IF structure, the 
OBRANCH in the preceding IF statement is resolved by executing an ENDIF or THEN . If the is lerc out or u.e 

terminator THEN (or ENDIF ) resolves the offset. 

foolproof however. An ELSE followed by another ELSE will not be detected by checking for a 2 since ELSE also leaves a 2. 

The run time action (Sequence 3) of ELSE is to prevent execution o^f^theOBRA^ 

Note that ELSE is an IMMEDIATE word. This means that its precedence bit is set, and it will therefore execute at compile time. 


COMPILE TIME (Sequence 2h 

* At entry - The top of the parameter stack contains the 16-bit signed single precision value 2 used for compiler security. 
The^econd stack entry contains a 16-bit address specifying the memory location where the offset is to be stored. (This 
address is also used to compute the offset itself.) 

* At exit - The top of the parameter stack contains the 16-bit signed single precision value 2 used for compiler security. 
The second stack entry contains a 16-bit address specifying the memory location where the offset is to be stored by 
terminating THEN or ENDF . (This address is also used to compute the offset itself.! 

EXECUTION TIME (Sequence 3): 


* At entry - No parameters. 

* At exit - No parameters. 


LIKELY ERROR MESSAGES: 

COMPILATION ONLY (11H) — This word may only be used within a colon definition. 

CONDITIONALS NOT PAIRED (13H) - There is some sort of problem with the pairing of conditionals within the definition being 
compiled. 


ELSE is a high level colon definition. 


Refer to F , THEN , ENDF , and BRANCH . 


FORTH-79: 

Definition: 


The FORTH-79 equivalent for ELSE is ELSE . 

. ELSE ( offset address \ 2 -- offset address\2 ) ( compile time ) 

2 7P.AIRS COMPILE BRANCH HERE 0 , SWAP 2 
COMPILE ENDF 2 ; IMMEDIATE 
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COMPILE TIME action of ELSE (Sequence 2): ( offset address\ 2 - offset address \ 2 ) 


DOCOL 


2 


7PAIRS 


COMPILE 


BRANCH 


HERE 



Set up for 7PAIRS . 


A preceding IF will 
have left a 2 on the 
stack. If the IF is 
missing (i.e., the 2 is 
missing) issue an error 
message and QUIT . 


This puts BRANCH into 
the definition being 
compiled. 


BRANCH is compiled 
into the definition. It is 
not executed at compile 
time. 


Get the location that 
the OBRANCH in the IF 
will branch to. i.e., 

The first word in the 
"false portion". 


Set up for ,. 


Store 0 into the 
dictionary as a place 
holder for the branch 
offset. 


Now compile an ENDIF 
into ELSE . The purpose 
of this ENDIF is to 
cause the OBRANCH in 
the IF to branch to the 
"false portion" of the 
structure at Sequence 3 
time. 


SWAP 


2 


[COMPILE ] 


ENDIF 


2 


;s 


IMMEDIATE 



Set up for ENDIF . 
Bring the address of 
the branch offset 
location of the 
previous IF to the top 
of the stack. 


Set up for ENDIF . 
ENDIF expects a 2 on 
the top of the stack. 


Since ENDIF is an 
IMMEDIATE word, 
[COMPILE ] must be 
used to compile it into 
the definition. 
[COMPILE ] is only used 
to compile ELSE (at 
Sequence 2) and does 
not exist in ELSE's 
definition when ELSE is 
executed at compile 
time (Sequence 2). 


Set the OBRANCH 
offset in the preceding 
IF to branch to and 
execute the "false 
portion" of the 
structure. This will 
execute during 
Sequence 2 when ELSE 
executes. 


The ENDIF which 
terminates this 
structure also expects 
a 2 to be on the top of 
the stack. 


ELSE is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 
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EXECUTION TIME action of ELSE (Sequence 3): ( — ) 



"true portion", execute 
the BRANCH and skip 
around the "false 
portion" using the 
previously calculated 
and stored forward 
branch offset. 


/rai qpY 


This is the entry point 
branched to by the 
false path of the IF 
statement. 


THEN 


til 

X 


"False portion" of 
IF structure. 


^AFTERTHEN J- 


This is the entry point 
the ELSE branches to. 
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EMIT 

EMIT ( character to EMIT — ) 

EMIT outputs the character on the top of the stack to the output device. 

TYPE is an example of a word which uses EMIT . 

* At entry - The top of the parameter stack contains a 16-bit value of which the low order 8-bits are to be output. 

* At exit - No parameters. 

EMIT is a high level colon definition. 

Refer to OUT . 

FORTH-79: The FORTH-79 equivalent for EMIT is EMIT . 

Definition: : EMIT ( character —) 

PE MIT 1 OUT +1 ; 


DOCOL 


PEMIT 


1 


OUT 


;s 



8080 fig-FORTH 
Version 1.1 


Low level 8080 
fig-FORTH Version 1.1 
word. 


Set up for +1 . 


Set up for +! . 


Increment OUT by 1. 
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EMPTY-BUFFERS 

EMPTY-BUFFERS ( - ) 

EMPTY-BUFFERS erases the contents of all of the buffers to zero. All update bits are erased to zero. Note that the null terminating 
word at the end of each buffer is also reset to zero. (Refer to +BUF for a detailed description of the buffers.) 

EMPTY-BUFFERS can be used to prevent modified (and subsequently "updated" data) from being written and therefore changing data 
already on disk. 

The word is also used just after system start-up, prior to any disk accesses. This is done because at start-up time, the buffers are 
un-initialized and contain random data. It is possible that the update bit of a buffer may be randomly set on and the block number may 
be a valid block number. If this happened, random data would be written over a valid block on disk whenever BUFFER first allocated 
that buffer. 

The name EMPTY-BUFFERS is purposely made rather cumbersome to type to prevent accidental execution because of its potentially 
destructive power. 

* At entry - No parameters. 

* At exit - No parameters. 

EMPTY-BUFFERS is a high level colon definition. 

Refer to +BUF , UPDATE , and FLUSH . 

FORTH-79: The FORTH-79 equivalent for EMPTY-BUFFERS is EMPTY-BUFFERS . 

Definition: : EMPTY-BUFFERS ( —) 

FIRST LIMIT OVER - ERASE ; 


DOCOL 


FIRST 


LIMIT 


OVER 




Set up for ERASE • Get 
the ending address for 
ERASE . 


Set up for - . Copy the 
beginning address 
"over" the ending 
address and put it onto 
the top of the 
parameter stack. 

Set up for ERASE . 
Calculate the number of 
bytes to erase by 
subtracting the copy of 
the beginning address 
from the ending 
address. This leaves 
the buffer length and 
beginning address still 
on the stack. 


Clear an area of 
memory starting with 
the specified 
location for the 
specified number of 
bytes.__ 


(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


Clear the entire buffer 
array to zeros. 
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ENCLOSE 

ENCLOSE ( beg string addr \ offset to 1st non-delim\ offset to 1st delim \ offset to 1st unexamined char ) 

ENCLOSE performs a parsing function upon a given text string. Given a beginning text address and a delimiter character, ENCLOSE 
scans the text and leaves its results on the stack. These results are in the form of byte offsets from the beginning of the text address. 
The parameters returned by ENCLOSE are: 

1. An offset to the beginning of a delimited string (i.e., the first non-blank character). 

2. The offset to the end of that same string. 

3. The offset to the next byte to examine. 

4. The original beginning address. 

This primitive is normally used by WORD to parse the input data stream into individual words delimited by blanks. Note: To avoid any 
confusion, the "text string" parsed by ENCLOSE is a pure character string, not characters preceded by a length byte. (Actually, WORD 
creates the length byte using the offsets returned by ENCLOSE .) 

* At entry - The top of the parameter stack contains a 16-bit value of which the low order 8-bits are the delimiter 
character. The second stack entry contains the 16-bit beginning address (inclusive) of the text string to be parsed. 

* At exit - The general form of the parameter stack ipon exit is: 


Top of stack - 

Second entry - 
Third entry - 
Fourth entry - 


Offset (relative to specified beginning address) to first unexamined character (i.e., character at which to 
start next scan). 

Offset to the 1st delimiter after text. 

Offset to the first non-delimiter character. 

Beginning address of character string to parse as specified at entry. 


There are three specific conditions that may arise when parsing any given character string. The following is a description of each 
condition and a description of the stack upon exit from that condition: 


CONDITION 1 - Scan encountered a null character before encountering any non-delimiter characters. 

Condition of stack at exit: 

Top of stack - Offset to null. 

Second entry - Offset to byte following null. 

Third entry - Offset to null. 

Fourth entry - Beginning address of character string to examine. 

CONDITION 2 - Scan enountered non-delimiter character^) terminated by a null. 

Condition of stack at exit: 

Top of stack - Offset to null. 

Second entry - Offset to null. 

Third entry - Offset to first non-delimiter character. 

Fourth entry - Beginning address of character string to examine. 

CONDITION 3 - Scan encountered non-delimiter characters terminated by a delimiter character. 

Condition of stack at exit: 

Top of stack - Offset of first unexamined character. 

Second entry - Offset to first delimiter after non-delimiter characteKs). 

Third entry - Offset to first non-delimiter character. 

Eourth entry - Beginning address of character string to examine. 

NOTE: The fig-EORTH 8080 Version 1.1 of ENCLOSE cannot correctly parse undelimited text strings with a length of more than 233 
bytes. 
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ENCLOSE is a low level code primitive. 

Refer to WORD . 

FORTH-79: There is no FORTH-79 equivalent for ENCLOSE . 



Figure ENCLOSE-1 
High Level Flow Chart for ENCLOSE 

NOTE: Each box roughly corresponds to a curly bracketed notation in the low level flow chart. 











NEXT 



Character string 
contains at least one 
non-delimiter and 
non-null character. 


;rl 


jExamine next character^ 

Scan for a null or 
delimiter. 


^ENCli) 


_ 

Push prese 
as first de 
after text. 

nt offset 
imiter 



Push prese 
also as off 
the first c 
examined. 

nt offset 
set to 
lar not 


Null encountered in 
character string before 
a delimiter was 
encountered. Set up 
return parameters for 
Condition 2 and exit. 


In this case, it is a 
null. (Second stack 
entry at exit.) 


NOTE: Null stops search 
immediately so it is 
also first char not 
included. (Top of stack 
at exit.) 
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NEXT 



NEXT 









END 


EM) 


COMPILE TIME (Sequence 2): ( loop address \ 1 — ) 
EXECUTION TIME (Sequence 3): ( truth flag — ) 


li icic iui c cafiiuils lwu ui i i ereiiL sbls u i auHons; tnose actions at compile time ana tnose at execution 


Note: "END" has been replaced by UNTIL . This is because END will eventually replace ; . UNTIL is the preferred usage, but 
still valid. 


time. 
END is 


END is used to mark the end of an indefinite, conditional loop structure where repetition continues until the boolean input to END is 
true. 


END is used in the form: 


BEGIN "Loop Body" END 


( UNTIL should be used in place of END .) 

BEG1N-END structures must always be used within a colon definition. 

It is important to note that in using a BEGIN-END structure, the "loop body" will always be executed at least once. This is because the 
exit condition is not tested "until" after the "loop body" has been executed. This is known as a "post-test" loop. If the exit condition 
must be tested before "loop body" execution, the BEGIN-WHILE-REPEAT structure should be used instead. 

END is actually a Sequence 1 compiling word. That is END compiles (during Sequence 1) another compiling word, UNTIL , into its 
definition. Then (at Sequence 2) when END is executed, the word UNTIL does the actual compiling into the definition being created. 

The apparent Sequence 2 compile time action of END is to compile a OBRANCH into the dictionary. (Actually this is performed at 
Sequence 2 via the UNTIL which was compiled by END at Sequence 1.) Secondly, it resolves the "loop body" entry point address provided 
by BEGIN into a return branch offset used by the OBRANCH and stores this offset into the definition. 

Some compiler security is provided by checking for a 1 on the top of the stack. An END without a preceding BEGIN will probably not 
encounter a 1 on the top of the stack. (During compilation, BEGIN 1 saves a 1 on the top of the stack.) 

The execution time action (Sequence 3) of END is to provide a conditional repetitive branch back to the loop's corresponding BEGIN (i.e., 
the beginning of the "loop body"). The input parameter to BEGIN is a boolean flag. If this flag is false (0), control returns to the first 
word in the "loop body" (just after BEGIN ). If the boolean flag is true (not 0), no branch occurs and the loop is exited. That is, repetitive 
looping continues "until" the exit conditional is true. 

The OBRANCH, compiled into the definition at compile time, is what controls the looping. 

Note that END is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 


COMPILE TIME (Sequence 2): 

* At entry - The top of the parameter stack contains the 16-bit signed single precision value 1 used for compiler security. 

The second stack entry contains the 16-bit entry point address of the "loop body" portion of the BEGIN-END structure. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - The top of the parameter stack contains a 16-bit signed single precision boolean flag used to control the 
conditional looping of the structure. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

COMPxLATION ONLY (11H) — This word may only be used within a colon definition. 

CONDITIONALS NOT PAIRED (13H) - There is some sort of problem with the pairing of conditionals within the definition being 
compiled. 

END is a high level colon definition. 

Refer to UNTIL , BEGIN and OBRANCH . 

FORTH-79: The FORTH-79 equivalent for .END is UNTIL . 

Definition: : END ( loop address\ 1 — ) ( compile time ) 

[COMPILE] UNTIL ; IMMEDIATE 
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COMPILE TIME action of END (Sequence 1): ( loop address \ 1 — ) 


DOCOL 


[COMPILE] 


UNTIL 


;S 


IMMEDIATE 



END is simply a 
redefinition of UNTIL 
but since UNTIL is an 
IMMEDIATE word, 
[COMPILE] must be 
used to compile it into 
the definition. (Other¬ 
wise it would execute 
instead of being 
compiled.) [COMPILE ] 
is only used (at Sequence 
1) to compile UNTIL 
into END and does not 
exist in END's 
definition when END is 
executed at compile 
time (at Sequence 2). 


UNTIL will be executed 
at a later compile 
time (Sequence 2) when 
END is executed. 


END is a compiler word 
and therefore must 
execute during 
compilation (Sequence 
1) so that it can 
compile UNTIL into the 
definition. 


EXECUTION TIME action of END (Sequence 3): ( truth flag — ) 


Refer to UNTIL . 







ENDIF 


ENDIF 

COMPILE TIME (Sequence 2): ( offset address \ 2 — ) 

EXECUTION TIME (Sequence 3): ( - ) 

ENDIF is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution 
time. 

E^i?! F ‘ S USed t0 mark 016 end of an IF_ENDIF or IF-ELSE-ENDIF structure. ( THEN is the preferred usage, but ENDIF is still valid ) 
ENDIF must be used in the form: 

IF "true portion" ENDIF 
OR 

IF "true portion" ELSE "false portion" ENDIF 


An IF-ENDIF structure must be used within a colon definition. 


The compile time (Sequence 2) action of ENDIF is to compute a forward branch offset, calculated from the supplied Offset Address to 
the next available memory location following ENDIF (supplied by the HERE in ENDF) and to store that offset in the location reserved 
by the previous F or ELSE statement. 


OFFSET 
points 
to ENDF 
cell. 



Some compiler security is provided by checking for a 2 on the top of the stack. IF and ELSE leave a 2 on the stack at compile time 
(.Sequence 2). Since no other conditional or looping words leave a 2 on the stack, failure to pair an ENDIF with an IF or ELSE will cause 
an error condition to be detected and signaled via 7PAIRS . 


The execution time (Sequence 3) action of ENDF is to simply serve as the destination of a forward branch from a previous IF or ELSE 
statement. It is just a label. 


Note that ENDF is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 


COMPILE TIME (Sequence 2)z 

At entry - The top of the parameter stack contains the 16-bit signed single precision value 2 used for compiler security. 

The second stack entry contains a 16-bit address used to calculate the branch offset address of a previous IF or ELSE . 

The second stack entry is also the memory location that offset is to be stored into. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - No parameters. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

COMPILATION ONLY (11H) — This word may only be used within a colon definition. 

CONpHTONALS NOT PAIRED (13H) - There is some sort of problem with the pairing of conditionals within the definition beinq 
compiled. y 

ENDIF is a high level colon definition. 

Refer to IF , ELSE , and THEN . 

FORTH-79: The FORTH-79 equivalent for ENDF is THEN . 

Definition: : ENDIF ( offset address\ 2 — ) ( compile time ) 

7COMP 2 7PAIRS HERE OVER - SWAP 1 ; IMMEDIATE 
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COMPILE TIME action of ENOIF (Sequence 2): ( offset address \ 2 — ) 


DOCOL 


7COMP 


2 


7PAIRS 


HERE 


OVER 


SWAP 



ENDIF must be used 
within a colon 
definition. 


Set up for 7PAIRS . 


A preceding IF or ELSE 
will have left a 2 on 
the stack. If there is 
no 2, something is 
missing; issue an error 
message and QUIT . _ 


Get the location to 
which the previous IF 
or ELSE will branch. 


Set up for - . Place 
the previously supplied 
Q-f-feo^ location ovsr 
the branch destination 
location. 

Destination address 
minus the branch 
address equals the 
branch offset. 


Set up for 1 . 


Store the calculated 
forward branch offset 
into the branch 
location in the 
previous IF or ELSE 
statement. 


;S (Run time portion of 

; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


IMMEDIATE 


Set the nrecedence 
bit of the preced¬ 
ing definition so it 
will be executed at 
compile time and not 
compiled into the 
definition being 
compiled. 


ENDIF is a compiler 
word and therefore mui 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


EXECUTION TIME action of ENDIF (Sequence 3): ( — ) 

ENDIF serves as the destination of a forward branch from a 
previous IF or ELSE statement. ENDIF is simply a label and has 
no run time code or action. 
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ERASE 


ERASE ( beginning address \ # of bytes to erase — ) 

ERASE clears a specified region of memory to zeros (OH). 

ERASE is simply a FILL with the fill character (0) "hard coded". 

EMPTY-BUFFERS is an example of word which uses ERASE. 

* At entry - The top of the parameter stack contains the 16-bit single precision number of bytes to erase, 
entry contains the 16-bit beginning address of the memory to erase. 

* At exit - No parameters. 

ERASE is a high level colon definition. 

Refer to FILL . 


The second stack 


FORTH-79: ERASE is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". 

Definition: : ERASE ( beginning address\ # —) 

0 FILL ; 


DOCOL 


0 


FILL 


;S 



Set up for FILL . Set 
0 as FILL character. 
The stack now 
contains: 

0 

// of bytes 
beg address 

Erase memory to zeros. 
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ERROR 

ERROR ( message # — contents of IN \ contents of BLK ) 

ERROR displays some type of error message, stops compilation, and restarts interpretation from the terminal. 

The form of the error message to be displayed is governed by the contents of the user variable WARNING . 

If WARNING contains a negative number, a (ABORT) is performed and only the standard startup message is displayed. Note that 

(ABORT) may be modified to call a user created error routine. 

If WARNING contains a zero, the message number supplied as an input parameter is simply printed as an "error number". This is often 

used for non-disk installations or when a disk that does not contain the error messages is being used (e.g., "MSG if 2"). 

If WARNING contains a non-zero positive number, the input parameter is used as a line number offset relative to Line □ of Screen 4. The 

contents of this line is listed on the output device (e.g., "DICTIONARY FULL"). Note that message number 0 gives no message, just "?" 

(pronounced "huh?"). Also note that the error message number may be a negative value. It will still be referenced via Line 0 of Screen 4. 

The contents of IN and BLK are saved to aid in determining where and why the error occurred. 

Some systems use a word called WHERE which inputs this information and displays the line and word where the error occurred. 

TERROR is an example of a word which uses ERROR . 

* At entry - The top of the parameter stack contains a signed 16-bit number used as an offset in lines (either positive or 
negative) relative to Line 0 of Screen 4. Either the number or the contents of the specified line will be displayed if 
WARNING contains a positive number. 

* At exit - The top of the parameter stack contains the 16-bit block number of the block being interpreted when the error 
occurred (the contents of the user variable BLK ). The second stack entry contains the 16-bit relative byte location of the 
next word to be interpreted (the contents of the user variable IN). These two parameters can then be used to aid in 
determining where and what the error was. 

ERROR is a high level colon definition. 

Refer to MESSAGE , WARNING , IN , and BLK . 









HERE 


COUNT 


TYPE 


II 711 


MESSAGE 


sp: 


IN 


@ 


BLK 


@ 
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{ List the word that I 
caused the ERROR .r 

Set up for COUNT . 
During interpretation, 
words are read into 
memory starting where 
HERE is pointing. 


Set up for TYPE . 
Convert the address of 
the message into the 
parameters required for 
TYPE . 


List the character 
string that could not 
be interpreted. 


Follow the TYPEed 
character string with a 
question mark. 


MESSAGE uses the line 
number that was the 
input parameter to 
ERROR . If WARNING 
is 0, only the number is 
listed. Otherwise, the 
number is used as an 
offset from line 0 of 
screen 4. 


Drop everything that is 
now in the parameter 
stack. 


I Place the contents of 
^ IN and BLK on the 
I parameter stack. 


Set up for (a) . IN 
contains the location 
of the next word to be 
interpreted. 


Place the contents of 
IN onto the stack for 
future reference. 


Set up for ja) . BLK 
contains the block 
number being 
interpreted. 


Place the contents of 
BLK onto the stack for 
future reference. 


QUIT 


;s 


Initialize tt 
return stac 
compilatior 
start interp 
from the in 
terminal. 

le 

k, stop 

l , and 
reting 
put 



(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


Stop compilation, go 
back to the terminal 
and wait for operator 
response. 














EXECUTE 


EXECUTE ( Code Field Address — ) 


EXECUTE "executes" the definition whose Code Field Address ( CFA ) is on the top of the parameter stack, 
control to the definition whose CFA is on the top of the stack, executes that definition only, and then 
definition foiiowing EXECUTE . 


That is, EXECUTE transfers 
returns control to the next 


This is action identical in philosophy to the IBM 360/370 EX (execute) instruction. 

EXECUTE is the means by which vectored execution arrays can be used in FORTH. 

EXECUTE is the "heart" of INTERPRET . The dictionary is searched for each incoming word in the data stream. When the word is 
found, its CFA is placed on the stack and the definition is then executed via EXECUTE . 

The internal operation of EXECUTE is quite simple. The top of the stack is moved into W and then a jump indirect is performed through 
W. W is then incremented to point to the Code Field of the definition being executed. 

This operation is quite similar to that of NEXT except that the address of the next definition to execute comes from the top or me 
parameter stack instead of from IP. 

* At entry - The top of the parameter stack contains the CFA of the definition to be "executed". 

* At exit - No parameters. 

EXECUTE is a low level code primitive. 

Refer to NEXT , and INTERPRET . 

FORTH-79: There is no FORTH-79 equivalent for EXECUTE . 


("execute) 


Pop the top of the 
parameter stack into 
W. 


NEXT1 


Place 


the CFA into W. 


Jump indirect to 
execute the specified 
definition. Control 
will return back to 
where IP is pointing, 
(i.e.. The definition 
following execute.) 
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EXPECT 

EXPECT ( beginning text destination address \ character count — ) 

eiiountIred PUtS CharaCterS from the terminal to tha specified address until the specified count is reached or until a carriage return is 


'h appended fc ° th f end 0f „^ e ' ext st r ream * ^ carriage return character is always replaced with a blank followed by a 
null. The blank and null are delimiters for WORD and INTERPRET . y 

ChB £ S f °J backspace cha racters. If a backspace is encountered, the loop Index is decremented so that the backspace is not 
pTnnnni-T h k Th ®. character is stm included in the text stream. If the backspace character was 

th l character position, i.e., trying to back up past the beginning; the character (which is an ascii 08) is decremented 

was^dec^nented V when^he ba^s^^e^a ^enc^nterecQ F ^ the (Tte 

iha™eS ^ R , T o H blc n o~ve: ^ SWitChi " 9 W ° rd ' ^ ^ ut ^ -» <* -era, ter mi na,s causes 

QUERY is an example of a word which uses EXPECT . 

* A ^ 6 !J , f y ^ ta *. °f the Parameter stack contains a signed 16-bit single precision character count value. This value is 
added to the specified address to determine the DO-LOOP Limit, so although negative values are legal, great care must be 

exercised in their use. The second stack entry contains the 16-bit beginning memory address where the text stream is to 
D 0 stored* 

* At exit - No parameters. 

EXPECT is a high level colon definition. 

Refer to QUERY . 


FORTH-79: The FORTH-79 equivalent for EXPECT is EXPECT . 

Definition: : EXPECT ( beginning text destination address\ count — ) 

OVER + OVER 
DO 

KEY DUP 0E +ORIGIN (a) = 

IF 

DROP 08 OVER I = DUP R> 2 - + >R - 

ELSE 

DUP 0D = IF 

LEAVE DROP BL 0 

ELSE 

DUP 

THEN 

I Cl 0 I 1+ : 

THEN 

EMIT 

LOOP DROP ; 


DOCOL 


OVER 


+ 


OVER 
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Set up for + . 


Set up for DO . Add 
beginning address to 
limit to calculate 
"Limit" for DO . 


Set up "initial" value 
for DO . Put beginning 
address on the top of 
the stack. 


(DO) 


DO 




KEY 


Move loop control 
characters (Index 
and Limit) to the 
return stack. 




Wait for ar 
terminal k 
Place the e 
value of th 
character 
top of the 
stack. 

input 

sypress. 

iscii 

e 

jnto the 
oarameter 


This execution time 
portion of DO is 
compiled into the 
definition by DO . 


This is the entry point 
for the jump from the 
LOOP portion of this 
DO-LOOP structure. 


Read a character from 
the keyboard. 


r° 


Determine if the input 
< character is a 
backspace. 









DUP 


LIT 

OEH 


+ORIGIN 


(Sj 


F 


DROP 


LIT 

08 


OVER 



DUP 


R> 


2 


+ 


>R 


Replace the top two 
values on the 
parameter stack with 
a true flag (1) if 
they are equal or a 
false flag (0) if 
they are not equal. 


Duplicate the top 
value on the 
parameter stack. 


Is the current 
character address equal 
to the beginning 
address? 


Backspace must 
"reset/backspace" the 
loop Index so can still 
input maximum number 
of characters. 


Duplicate the truth 
flag result of the 
previous equal. 


Remove the top value 
of the return stack 
and place it onto 
the top of the 
parameter stack. 


Subtract the top 
stack entry from the 
second stack entry 
and replace the two 
values with their 
signed difference. 


Add the top two 
stack values and 
replace them with 
their signed sum. 


Remove the top value 
of the parameter 
stack and place it 
onto the top of the 
return stack. 


Subtract the top 
stack entry from the 
second stack entry 
and replace the two 
values with their 
signed difference. 




Place the constant 
value 2 onto the top 
of the parameter 
stack. 




Get the DO loop Index 
value from the return 
stack (i.e., current 
address). (This is not 
a recommended 
programming technique.) 


Set up for - 


Back up current address 
two bytes. 


Add the truth flag 
result of comparing 
current address with 
beginning address: 

0 = Not at first char 
1 = At first char so 
can't backspace 


Put the adjusted DO 
loop Index value back 
on the return stack. 


Cause a beep if tried 
to backspace from the L 
beginning character j 
location. J 


Subtract the DUP 'ed 
truth flag from the 
backspace character 
(previously LIT 08). If 
a backspace was 
attempted from the 
beginning character 
location the truth flag 
is a 1. Leave either a 
BELL or a BACKSPACE 
character on the stack. 
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This is the entry point 
for the previous IF . 
(i.e., the character 
was not a carriage 
return.) 


Duplicate the 
character. 


This is the entry point 
from the "true portion" 
of the previous IF . 
(i.e., the character 
was a carriage return.) 


Get the character 
string address to store 
the character. 


Store one of the 
following: 

1. The character. 

2. A backspace char. 

3. A bell if tried to 

backspace from the 
beginning char 
position. 

4. A null if a C/R 
was entered. 


Set up to put a null at 
the end of the 
character string as it 
now exits (even though 
this may not yet be the 
end). 


Get the current 
character address. 


Point to the next 
character location. 


Store the null in the 
next character 
location. 


This is the entry point 
from "true portion" of 
the IF which compared 
for a backspace. 


Echo the character back 
to the terminal, 
including a backspace 
character or bell or 
carriage return. 


This execution time 
portion of LOOP is 
compiled into the 
definition by LOOP . 
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LOOP 


DROP 


;s 
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FENCE 


FENCE ( — data address ) 

FENCE is a user variable used in conjunction with EORGET to set a boundary past which EORGET cannot forget. This prevents the 
programmer from inadvertently forgetting too much of the dictionary. EENCE is initialized at start up time by COLD with data from 
the origin parameter area but its contents may be changed at any time to reflect a new dictionary structure. 

The words? 


'EROG EENCE 1 

will not allow forgetting below the named definition (in this case, EROG ). 

The user variable EENCE is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable EENCE . 

Refer to EORGET , and USER . 

FORTH-79: There is no EORTH-79 equivalent for FENCE . 
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FILL 


FILL ( start address \ count \ fill character — ) 

FILL "fills" each location of a specified region of memory with a specified byte value. 

Note: This word may be installation dependent on other than 8-bit machines. 

This version of FILL differs from the fig-FORTH model in that it is a low level code primitive. The high level version of FILL (based on 
CMOVE ) works correctly when filling read/write memory. However, it will not work correctly when filling write-only memory such as 
specialized video display memory. This is because the "ripple fill" used by CMOVE requires that the byte to be moved be read from 
memory. This code version of FILL does not use CMOVE or "ripple fill" and therefore will work correctly when filling write-only 
memory. 

ERASE and BLANKS are examples of words that use FILL . 

* At entrv - The top of the parameter stack contains a 16-bit value of which the low order 8-bits are the fill character. The 
second stack entry contains a 16-bit unsigned "count", i.e,, the number of locations to fill. The third stack entry contains 
a 16-bit "starting address" (inclusive). 

* At exit - No parameters. 


FILL is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for FILL is FILL . 



8080 fig-FORTH 
Version 1.1 



BEGIN function starts 
here, (i.e., This is 
the entry point from 
the loop back to fill 




REPEAT function of 
ioop. (i.e., Go fill 
another location.) 



NEXT 
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FIRST 

FIRST ( — address) 

FIRST is a single precision CONSTANT value. This constant places the memory address of the "first" (lowest) block buffer in the buffer 
array onto the top of the parameter stack. Refer to +8UF for an example of the usage of FIRST . Also see BLOCK and BUFFER for a 
description of the buffer array. 

Conversely, LIMIT is the constant that reflects the upper "limit" (highest) block buffer address. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the 16-bit memory address of the first buffer in the buffer-array. 

Refer to LIMIT , +BUF , BLOCK , and BUFFER . 

FORTH-79: There is no FORTH-79 equivalent for FIRST . 
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FLD 

FLD ( — data address ) 

FLD (pronounced "F-L-D") is a user variable which is intended to control field length in pictured numeric output. 

FLD is not currently used in the fig-FORTH model. 

The user variable FLD is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable FLD . 

FORTH-79: There is no FORTH-79 equivalent for FLD . 
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FLUSH 


FLUSH ( - ) 


FLUSH writes to disk all the buffers in the buffer array that have been flagged as "updated". 

FLUSH is FORTH's virtual memory equivalent to "traditional" languages "write-to-disk" command. 

A buffer is flagged as being "updated" when the most significant bit (i.e., the update bit) in the header portion of a buffer is set to one. 
(Refer to +BUF for a detailed explanation of the buffer structure.) This update bit is set via the word UPDATE . 

Flagged buffers will automatically be written to disk by BUFFER when the buffer is allocated to a new block number while executing 
BLOCK . Sometimes it is desirable or even necessary to force writing of these updated buffers from memory to disk before this 
re-allocation takes place. 

Examples of when it is desirable to FLUSH the buffers are: 

1. Before changing disks (this ensures that the updated data is written to the proper disk). 

2. Before leaving FORTH. 

3. Before powering down the system. 

Typing FLUSH immediately after finishing editing a source screen is a good habit to develop to prevent inadvertently removing a disk 
before the newly edited data is written to it. 

If there are no "updated" buffers (buffers with a set update bit), FLUSH has no effect. Executing EMPTY-BUFFERS prior to executing 
FLUSH means no data will be written to disk. 


The basis of FLUSH is BUFFER . The word BUFFER is contained within a DO-LOOP which is executed as many times as there are 
buffers in the buffer array. BUFFER then re-allocates each buffer and writes any "updated" buffer data to disk. 


Note that, within FLUSH , BUFFER re-allocates each buffer to block number 0 (8080 fig-FORTH Version 1.1). A side effect of this 
operation is that a reference (with BLOCK) to a block that was in memory prior to the execution of FLUSH will cause a disk access. This 
happens because the buffer allocation scheme has been re-initialized even though the data portion of the block is still in memory. 

* At entry - No parameters. 

* At exit - No parameters. 

FLUSH is a high level colon definition. 


Refer to BUFFER , +BUF , UPDATE , and BLOCK . 


FORTH-79: The FORTH-79 equivalent for FLUSH is SAVE-BUFFERS . 


Definition: 


DOCOL 


NBUF 


1 + 


: FLUSH ( -) 

NBUF 1+ 0 DO 

0 BUFFER DROP 
LOOP ; 



I Set up loop count 
^ parameters for 
IpO-LOOP . 


Set up for DO . Get 
the number of buffers, 
i.e., The number of 
times to loop. 


Set up for DO . Create 
the "Limit" parameter 
for DO . (The Limit 
must be 1 more than the 
desired number of 
loops.) 



Set up for DO . Set the 
"initial" parameter for 
DO to 0. 


This execution time 
portion of DO is 
compiled into this 
definition by DO (at 
FLUSH's Sequence 2). 


This is the entry point 
for the jump from the 
LOOP portion of this 
DO-LOOP structure. 


j^Flush" one buffer!| 


Set up for BUFFER . 

Tell BUFFER to allocate 
buffers to block number 

0 . 
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BUFFER 


DROP 


(LOOP) 


LOOP 


;S 








FORGET 

FORGET ( - ) 

FORGET deletes definitions from the dictionary. The specified definition and all definitions following, up until the end of the dictionary, 
are "forgotten". 

FORGET is used in the form: 


FORGET "definition name" 

In the fig-FORTH version of FORGET , the programmer must ensure that the CONTEXT and CURRENT vocabularies are the same or the 
error message DECLARE VOCABULARY will be issued and the FORGET will QUIT or ABORT . 

FORGET searches the dictionary for the first occurrence of the specified definition name and changes DP (the Dictionary Pointer) to 
point to the located definition. That definition (and all following) is "forgotten" and will be overlayed when the next new definition is 
created. The CONTEXT and CURRENT vocabulary linkages are also modified to drop the forgotten definitions from the vocabulary 
chain. 


FORGET is a very powerful word. It is possible to forget the entire dictionary, including FORTH itself. To limit the scope of this 
powerful word and to prevent accidental forgetting of important definitions, the user variable FENCE is used. FENCE is a user variable 
which contains an address below which it is not possible to FORGET . 

WARNING: Using FORGET in a system comprised of multiple vocabularies will probably (but not necessarily always) cause the system to 
crash. 

FORGET , as defined in the fig-FORTH Model, is "unaware" of any vocabularies other than the vocabulary referred to by CONTEXT and 
CURRENT . As described in VOCABULARY , multiple vocabularies are logically structured like branches on a tree; but they are 
physically structured as a one-dimensional linked list. The fig-FORTH Model version of FORGET simply uses "brute force" to forget a 
portion of this one-dimensional dictionary from the end up to and including the specified definition. The fact that there may be 
vocabulary links which now point into a "forgotten" dictionary is not taken into account. Any reference to such a vocabulary having a 
"broken" chain will produce undeterminable results. 

* At entry - No parameter stack entries. The word immediately following FORGET in the input data stream is the name of 
the definition to be "forgotten". 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

PROTECTED DICTIONARY (15H) — The address of the definition being "forgotten" is less than the value stored in FENCE . Change the 
value in FENCE . 


DECLARE VOCABULARY (18H) — CONTEXT and CURRENT are not aiming at the same vocabularies when attempting to FORGET . 
FORGET is a high level colon definition. 


Refer to FENCE , and VOCABULARY . 


FORTH-79: The FORTH-79 equivalent for FORGET is FORGET . 


Definition: 


DOCOL 


CURRENT 


@ 


186 


: FORGET ( - ) 

CURRENT fa) CONTEXT (a) - 18 TERROR [COMPILE ] ' 

DUP FENCE (3 <15 TERROR DUP NFA DP I 


LFA 13 CURRENT (3 i ; 



Set up for (3 . 


Set up for - . Pick up 
the address of the top 
of the CURRENT 
vocabulary. 


CONTEXT 


!§ 


LIT 

18H 



Set up for (3 . 


Set up for - . Pick up 
the address of the top 
of the CONTEXT 
vocabulary. 


Set up for TERROR . 

If CONTEXT equals 
CURRENT , the "truth 
flag" will be false and 
TERROR will not be 
executed. 


Set up for TERROR . 
Place the error message 
number onto the stack. 







?ERROR 


[COMPILE ] 


DUP 


FENCE 


@ 


< 


LIT 

15H 


TERROR 



Issue an error message 
and QUIT if CURRENT 
and CONTEXT 
vocabularies are not 
equal. 


Since 1 is an IMMEDIATE 
word, [COMPILE ] must 
be used to compile it 
into the definition. 
(Otherwise it would 
execute instead of 
being compiled. 
[COMPILE] is only used 
at Sequence 1 time to 
"compile" ' into 
FORGET and does not 
exist in FORGET's 
definition when 
FORGET is executed 
at compile time 
(Sequence 2). 


Get the address of the 
definition to FORGET 
to. A QUIT will occur 
if no match is found. 


Set up for < by making 
a copy of the PFA . 


Set up for (a) . 
Definitions located 
bslow the address in 
FENCE cannot be 
forgotten (i.e., 
"protected memory"). 


Set up for < . Pick up 
the address in FENCE . 


Set up for TERROR . 
Set the truth flag to 
true (1) if the specified 
definition's address is 
below that in FENCE . 


Set up for TERROR . 
Place the error message 
number onto the stack. 


Issue an error message 
and QUIT if trying to 
forget past FENCE . 


DUP 


NFA 


DP 


LFA 


fa) 


CURRENT 


fa) 


;S 



Set up for NFA by 
duplicating the PFA on 
the top of the stack. 


Set up for 1 . Get the 
Name Field Address of 
the specified 
definition. 


Set up for 1 . DP 
contains the Dictionary 
Pointer. 


Store the PFA of the 
specified definition 
into DP thereby 
"FORGETting" the 
dictionary words above 
the definition. 


Set up for . The LFA 
of the "forgotten" word 
must be used as the 
CURRENT vocabulary 
pointer. 


Set up for I . Pick up 
the pointer to the 
CURRENT vocabulary 
pointer. 


Set up for la) 


Set up for I . Pick up 
the address of the 
CURRENT vocabulary 
pointer. 


Force the CURRENT 
vocabulary pointer to 
equal the present 
CONTEXT vocabulary. 
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FORTH 


FORTH ( - ) 

is 5 he name of the "vocabulary" definition for the FORTH vocabulary. The FORTH vocabulary contains all of the standard 
FORTH definitions. Executing FORTH sets CONTEXT to point to the FORTH vocabulary. This will cause dictionary searches to begin 
with the FORTH vocabulary. Since CONTEXT now points to FORTH , executing DEFINITIONS would then cause new definitions to be 
appended to the FORTH vocabulary. 


The FORTH vocabulary is the topmost vocabulary. All other vocabularies will be appended under FORTH . At cold start initialization, 
the user variable VOC-LINK is initialized to point to FORTH . 

J™ e ,T, P Sc ™ definition is crea ted via the word VOCABULARY . VOCABULARY is a <BUILDS DOES> definition. This means that the 
j r ... P° rtl . on . creates the actual FORTH definition in the dictionary at Sequence 2 time. The DOES> portion of the VOCABULARY 
definition contains the definitions that will be executed when FORTH is executed at Sequence 3 time. i.e., The FORTH definition 
contains a pointer to its execution time procedure which "lives" in VOCABULARY and at execution time the run time code for DOES> 
transfers control to that procedure in VOCABULARY . 

A more detailed explanation of vocabularies can be found in VOCABULARY . The definition FORTH is used as an example in the 
descriptions of the words <BUILDS and DOES> . 

* At entry - No parameters. 

* At exit - No parameters. 

FORTH is a high level colon definition. 

Refer to VOCABULARY , CONTEXT , CURRENT , DEFINITIONS , <BUILDS , DOES> , and VOC-LINK . 

FORTH-79: The FORTH-79 equivalent for FORTH is FORTH . 

Definition: : FORTH ( —) 

VOCABULARY FORTH ; IMMEDIATE 


DOCOL 


DODOES 


DOVOC 



FORTH is created by 
VOCABULARY which is 
a <BUILDS DOES> word. 


This code is defined 
within the 
VOCABULARY 
definition executed 
(called) when a 
definition created 
by vocabulary is 
executed. 


The following code 
exists in the DOES> 
portion of the 
VOCABULARY 
definition. 


2 + 


CONTEXT 


;S 



The run time code for 
DOES> places the 
Parameter Field Address 
of the definition being 
executed onto the top 
of the parameter stack. 
In this case, that is 
the Pseudo Name Field. 
Adding two to this 
gives the address of 
FORTH's Vocabulary 
Link Field. 


CONTEXT contains a 
pointer which points to 
the Vocabulary Link 
Field of the vocabulary 
to be searched first. 


Set CONTEXT to point 
to the FORTH 
vocabulary. 
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HERE 


HERE ( - address ) 

HERE places the address of the next available dictionary location onto the parameter stack. The use of HERE is the proper way to 
obtain the location of the end of the dictionary (e.g., DP (§ on some implementations will return a wrong address). 

HERE is used in such basic words as , (comma) and also in higher-level words such as ." (dot-quote). 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the next available dictionary location. 

HERE is a high level colon definition. 

Refer to DP. 

FORTH-79: The EORTH-79 equivalent for HERE is HERE . 

Definition: : HERE ( — address) 

DP fa) ; 


DOCOL 


DP 


;s 



8080 fig-FORTH 
Version 1.1 


DP (Dictionary Pointer) 
contains the address of 
the next available 
dictionary entry. 


i.e., Pick up " HERE ". 
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HEX 


HEX (-) 

HEX sets the user variable BASE to 16 (decimal). This causes all numeric input and output conversions to be performed in hexidecimal 
(base 16). 

Note that this is not an IMMEDIATE word. 

* At entry - No parameters. 

* At exit - No parameters. 

HEX is a high level colon definition. 

Refer to (NUMBER) , and BASE . 

FORTH-79: The FORTH-79 equivalent for HEX is HEX . 

Definition: : HEX ( --) 

10 BASE 1 ; 


DOCOL 


LIT 
10 H 


BASE 


;S 



Put the literal value 
10H (16 decimal) into 
BASE . 
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HLD 


HLD ( — data address ) 

HLD (oronounced "H-L-D") is a user variable which contains the address of the last character of text placed into PAD during 
binary-to-ascii pictured numeric output conversion. <// initializes HLD and HOLD references HLD during conversion. 

The user variable HLD is stored as a 16-bit single precision value. When in memory, the high and low order bytes may De switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable HLD . 

Refer to <# , #> , HOLD , SIGN , NUMBER , (NUMBER) , and USER . 

- . —-r. • r-on “fl I "7Q l—II r\ 

runiti-/« mere is no ruri i n-/> ojunaicia ■ <->. . . 
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HOLD 


HOLD ( ascii char — ) 


HOLD stores an ascii character into the next available location in a pictured numeric output string. HOLD is used internally by // to 
p ace each converted ascii digit into memory. Numeric punctuation (characters such as commas, decimal points, signs, dollar signs, etc.) 
can also be placed in output strings via HOLD . a y ’ 


^ dr -. of ^ h®? 1 availab ! e location is kept m the user variable HLD . HOLD decrements HLD before each character store. HOLD 

7 USe :-T:' !f i 3 .expression, w is used to initialise HLD to the beginning of PAu . Therefore characters are stored into memory 

from high to low memory starting from one byte before the beginning of PAD working towards the end of the dictionary. 


SIGN uses HOLD to place a minus sign into an output string, 
output. 


? hfj description of <# and il explain the operation of pictured numeric 


* At entry - The top of the parameter stack contains an 8-bit value (normally an ascii character) in the low order portion of 
the topmost 16-bit word. The user variable HLD contains the memory location +1 where the character is to be stored. 

At exit - No parameters. However, the character is in memory and the contents of HLD has been decremented by 1. 

HOLD is a high level colon definition. 


Refer to // , <// , #> , SIGN , PAD , and HLD . 


FORTH-79: The FORTH-79 equivalent for HOLD is HOLD . 

Definition: : HOLD ( char — ) 

-1 HLD +1 HLD 19 Cl ; 


DOCOL 


LIT 

-1H 


HLD 


HLD 


i 


Cl 


;s 
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Set up for +1 . 


Set up for +1 . 


Decrement HLD by 1. 
(i.e. Aim at the next 
available string 
location.) 


Set up for (a) . 


Set up for Cl . Get 
the address to store 
the character. 


Store the character 
into the pictured 
numeric string. 










HPUSH 


HPUSH ( - value ) 

HPUSH is strictly an 8080 fig-FORTH Version 1.1 inner interpreter routine entry point. 

_ . hhi _„ a .,ooc fho 1 nnntftnts of the HL reqister pair to be pushed onto the top of the parameter stack before 

performing NEXT . 

Refer to NEXT . 
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I 


I ( — Index value ) 

I copies the current DO LOOP (or DO +LOOP ) Index onto the top of the parameter stack. 

This is analogous to the value I in a BASIC FOR-NEXT loop of the form: 

10 FOR I = 1 TO 10 
20 PRINT I 
30 NEXT I 

In most current FORTH implementations, the loop Index is kept on the top of the return stack. Implementation wise, this makes the code 
for the word I identical to that of the word R . However, there are no restrictions against keeping the loop Index somewhere else other 
than the return stack. Therefore, the word I (and not R ) should always be used to obtain the current loop Index for transportability. 
Conversely, the action of I is undefined outside of a DO-LOOP structure. 

Note that the return stack value is copied; not removed. 

LIST is an example of a word which uses I. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the 16-bit loop Index value. 

I is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for I is I. 



NEXT 
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ID 


ID. ( Name Field Address — ) 


ID. (pronounced "I-D-dot") lists the Name Field of a definition. 

ID. calculates the physical length of the Name Field by subtracting the Link Field Address from the Name Field Address. This length is 
t-hcr, to move the Name Field text, includinq the lenqth byte to PAD . The contents of the length byte (which may differ from the 
actual number of characters stored in'the dictionary, see WIDTH) is then used to TYPE the definition name. This may result in the 
physical Name Field being typed followed by trailing blanks (e.g., A WIDTH of 3 with a length of 7 would result in the first three 
characters of the name being typed followed by four blanks). 


VUST is an example of a word which uses ID. . 

* At entry - The top of the parameter stack contains the Name Field Address of the Name Field to be printed. 

* At exit - No parameters. 


ID, is a high level colon definition. 
Refer to WIDTH . 


FORTH-79: There is no FORTH-79 equivalent for ID. . 

Definition: : ID. ( NF A --) 

PAD 20 5F FILL DUP PFA LFA OVER - 
PAD COUNT IF AND TYPE SPACE ; 


DOCOL 


PAD 


LIT 

20H 


LIT 

5FH 


FILL 


DUP 



Set up beginning 
address for FILL . 


Set up for FILL . Fill 
32 (decimal) bypes of 
PAD with blanks. 


Set up for FILL . Make 
ascii "dash" the fill 
character. 


Fill PAD with dashes. 


fc, 


Calculate the physical^ 
^ length of the Name 
(Field. 




Duplicate the specified 
Name Field Address. Set 
up for PFA . 


PFA 


LFA 


OVER 


PAD 


SWAP 


PAD SWAP CMOVE 



Get definition's 
Parameter Field Address 
to set up for LFA . 


Get Link Field Address, 
The first byte of the 
Link Field occurs 
immediately after the 
last byte of the Name 
Field. 


Put Name Field Address 
onto the top of the 
stack. 



Link Field Address - 
Name Field Address = 
physical length of the 
name stored in the 
dictionary. 


JM 

L 


Move the name text into 
PAD . 


■} 


Get PAD address as 
destination for CMOVE . 


Set up parameters in 
order expected by 
CMOVE. 


195 



















CMOVE 

Move the specified 
byte string to the 
specified memory 
location. 

Move the Name Field, 
including its length 
byte, to PAD . Note 
that only the number of 




characters physically 
present in the 
dictionary are moved. _ 

PAD 

Place the address of 
the text output 
buffer onto the top 
of the parameter 
stack. 

Set up for COUNT . 





COUNT 

Place the text 
length and beginning 
text address onto 
the parameter stack. 

Set up for TYPE . Note 
that this picks up the 
length byte, which may 
differ from the number 




of name characters 
stored in the Name 

Field. 

LIT 

1FH 

Place the literal 
value 1FH onto the 
top of the parameter 
stack. 

Set up to strip off 

MSB, precedence and 
smudge bits. 





AND 

Logically AND the 
top two values on 
the parameter stack 
and replace them 
with the logical 
result. 

Strip off unwanted 
bits. All that remains 
is the logical length 
of the name. 





TYPE 

Output the specified 
text string. 

"Type" the definition 
name. Note: TYPE types 




as many characters as 
are specified in the 
length byte. 

SPACE 

Output an ascii 
space (20H) 
character. 






;s 

(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 
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IF 


IF 

COMPILE TIME (Sequence 2): ( - offset address \2 ) 

EXECUTION TIME (Sequence 3): ( truth flag - ) 

IF is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution time. 

F must be used within an F-THEN or F-ELSE-THEN structure. ( ENDIF may be used in place of THEN if desired but THEN is the 
preferred usage.) The format of these structures is: 

IF "true portion" THEN 
OR 

IF "true portion" ELSE "false portion" THEN 


(Beware — mis differs in form from the PASCAL F-THEN-ELSE structure.) 

F-THEN and F-ELSE-THEN structures must be used within a colon definition. 

The compile time (Sequence 2) action of IF is to compile a OBRANCH into the definition and then reserve the dictionary location 
followinq for the branch offset used as an input to OBRANCH . IF then places the address of this reserved location onto the parameter 
stack 90 ^that a following ELSE or THEN statment can calculate and store its entry point offset into the reserved location. To provi 
compiler security, the value 2 is placed onto the top of the parameter stack so that ELSE or THEN (or ENDIF ) can check for it. This 
provides a somewhat secure (but not foolproof) method of checking for un-matched IF's and THEN s. 


OFFSET points 
to ENDIF 
cell. 


F 


ENDIF 


OBRANCH 


OFFSET 


This address of this cell 
is left on the stack by IF. 

ENDIF then stores this 
offset value. 


The apparent execution time (Sequence 3) action of IF is to input a tota. flag from. the top of’the 

based on this flaq. (Actually OBRANCH is executed at execution time.; it tne fiag is hue v nun-ZoiQj, u.e po.«o.. -. ...e 
will be executed. Note that a true flag is any non-zero value; not just a 1. If the flag is false (0), the optional ELSE ( a se^por.ion 
the structure) will be executed if it is present. If an ELSE is not included in the structure, a false flag causes control to be passed to the 
word immediately following the THEN statement. 

After executing either the "true portion" or the "false portion" of the structure, control is passed to the word immediately following the 
THEN statement. 

Note that F is an IMMEDIATE word. This means that its precedence bit is set, and it will therefore execute at compile time. 


COMPILE TIME (Sequence 2)z 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the 16-bit single precision value 2. This value is checked by ELSE or 
THEN to provide compiler security. The second stack entry contains the 16-bit address of the location reserved or e 
OBRANCH offset. ELSE or THEN use this address to fill in the offset. 


EXECUTION TIME (Sequence 3): 

* At entry - The top of the parameter stack contains a 16-bit signed boolean truth flag. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

COMPILATION ONLY (11H) - This word may only be used within a colon definition. 

CONDITIONALS NOT PARED (13H) - There is some sort of problem with the pairing of conditionals within the definition being 
compiled. 

F is a high level colon definition. 

Refer to ELSE , ENDF , THEN , F , and OBRANCH . 

FORTH-79: The FORTH-79 equivalent for F is F . 

Definition: : IF ( - offset address\ 2 ) ( compile time ) 

COMPILE OBRANCH HERE 0 , 2 ; IMMEDIATE 
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COMPILE TIME action of F (Sequence 2): ( — offset address \ 2 ) 


EXECUTION TIME action of F (Sequence 3): ( truth flag — ) 


DOCOL 


COMPILE 


OBRANCH 


HERE 


0 


2 


;S 


IMMEDIATE 



This puts OBRANCH into 
the definition being 
compiled at Sequence 2. 


OBRANCH is compiled 
into the definition. It 
is not executed at 
compile time (Sequence 
2 ). 


This is the address of 
the word following 
OBRANCH . It will be 
filled in with the 
branch offset by ELSE 
or END IF . 


Set up for , . 


Store 0 into the 
dictionary as a place 
holder for the branch 
offset. 


ELSE or ENDIF expect a 
2 to be on the top of 
the stack. 


IF is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 



ELSE 

.(false) 


Execute the optional 
"false portion" of 
IF statement. 


THEN 



This entry point may be 
either the first word 
~1 following an ELSE (the 

optional "false 
portion") or the first 
word following a THEN . 

I _ 
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IMMEDIATE 


IMMEDIATE ( - ) 

IMMEDIATE sets the precedence bit of the most recently created definition. A definition whose precedence bit is set will be executed 
"immediately" by INTERPRET even when the system is in compile state (hence the name IMMEDIATE). 


This feature allows the compiler to be "extended". That is, definitions can be created to perform specific actions at compile time rather 
than modifying the compiler itself. INTERPRET is the word which detects that the precedence bit is set. 

It is possible to force the compilation of an IMMEDIATE definition by preceding it with [COMPILE] . (Otherwise the definition executes 
instead of compiles'.) 

The precedence bit in fig-FORTH is the 40H bit of the Name Field's length byte. The system is defined as being in compilation state 
when the user variable STATE contains a non-zero value. 

t- _ :_t __:i~,. f k ic npopl >./»-. i oh ic fianned TMMFDIATE by being followed bv the 

BEGIN is an example or a compiler woru va condiuunai Cum H uc. ..— y 

word IMMEDIATE . 


* At entry - No parameters. 

* At exit - No parameters. 

IMMEDIATE is a high level colon definition. 

Refer to INTERPRET , [COMPILE] , LASTEST , and STATE . 

FORTH-79: The FORTH-79 equivalent for IMMEDIATE is IMMEDIATE . 

Definition: : IMMEDIATE ( --) 

LATEST 40 TOGGLE ; 


DOCOL 


LATEST 


LIT 

40H 


TOGGLE 


;s 



Get the address of the 
most recently created 
definition. 


Set up for TOGGLE. 
Get the bit mask for 
setting precedence bit. 


Set the precedence bit. 
Make the definition 
IMMEDIATE . 
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IN 

IN ( — data address ) 

IN (pronounced "in") is a user variable that contains the byte offset from the beginning of the current inout text buffer (whether usinq the 
Terminal Input Buffer or a disk buffer). 

IN is set to 0 by QUERY (for TIB input) and by LOAD and —> (for mass storage input). WORD then references and increments IN as 
words in the buffer are moved to HERE . 

The user variable IN is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable IN . 

Refer to WORD , QUERY , LOAD , —> , HERE , and USER . 

FORTH-79: The FORTH-79 equivalent for IN is >IN (pronounced "to-in") . 


ZOO 



INDEX ( beginning screen number \ ending screen number — ) 


INDEX 


INDEX prints the first line of each screen within the specified range of screens inclusively. The index listing will be terminated if any 
terminal key is pressed. See 7TERMINAL . 

The basis of INDEX is a DO-LOOP which contains the word .LINE . The loop Index ( I) is used as an input parameter to .LINE to print 
the first line of each screen within the specified range. 

* At entry - The top of the parameter stack contains an unsigned 16-bit value specifying the last screen to be indexed. The 
second stack entry contains an unsigned 16-bit value specifying the beginning screen number to be indexed. 


* At exit - No parameters. 


INDEX is a high level colon definition. 


Refer to .LINE , and 7TERMINAL . 


FORTH-79: 

Definition: 


DOCOL 


LIT 

OCH 


EMIT 


CR 


1 + 


SWAP 


INDEX is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". 

: INDEX ( beginning screen number^ ending screen number ) 

OC EMIT CR 1+ SWAP 
DO 

CR I 3 .R SPACE 0 I .LINE 
7 TERMINAL IF LEAVE THEN 
















I 


• LINE 


7TERMINAL 


IF 


LEAVE 


THEN 



(LOOP) 


LOOP 
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INTERPRET 


interpret (-) imcfirnci 

INTERPRET is the FORTH text interpreter, commonly referred to as the outer interpreter. (The address interpreter, NEXT , is referred 
to as the inner interpreter.) 

The actions of INTERPRET are very straightforward. INTERPRET interprets the text input stream. This input stream comes from the 
terminal if BLK contains 0, or from mass storage if BLK contains a block number. 

INTERPRET will either execute (i.e., "interpret" in the traditional sense) or compile an input stream word depending upon the "state" of 
the system (as reflected by the value stored in the user variable STATE). STATE is set to compile mode by a compiler word such as : 
and reset to interpret mode by a word such as ; . 

The overall loqic of INTERPRET is to select the next sequential word in the input stream and search the CONTEXT then CURRENT 
vocabularies for a match. If no match is found, an attempt is made to convert the "word" to a numeric value (using the current base). If 
this also fails, an error message is issued. 

If -FIND does find a match, the definition is either executed or compiled. Tests are made to determine if the word is IMMEDIATE or if 
the system is in inteipret mode. The word is EXECUTEd if either are true; otherwise, it is compiled into the dictionary. 

If a match was not found but the word was successfully converted into a numeric value, DPL is examinea to determine it the vaiue is to 
be treated as double or single precision. By convention, if a decimal point is encountered anywhere within a character string 
representing a valid numeric value, that value is treated as being double precision. Note that the only, function the decimal point serves 
is as a flag 9 to signify double precision. No "place holding" is implied. (The user variable DPL is used to loosely keep track of the decimal 
point location. See DPL , and NUMBER .) 

Then either DLITERAL or LITERAL is executed. These words test STATE internally and will either leave the value on the stack or 
compile it depending ipon the state of the system. 

INTERPRET examines the parameter stack pointer to determine if it is within its maximum and minimum address limits. If not, Error 
Message 1 (EMPTY STACK) or Error Message 7 (FULL STACK) is issued and a QUIT occurs. 

INTERPRET is an endless BEGIN-AGAIN loop and therefore has no way to terminate execution and exit back to the definition which 
"called" it. This peculiarity is solved via the word NULL (or X ). 

INTERPRET is used within two definitions: QUIT and LOAD . Data stream input when executed within QUIT comes from the terminal 
input buffer (TIB). Data stream input from LOAD comes from disk buffers. 

It is mandatory (and automatic unless a bug occurs elsewhere) that both of these buffers are ended with an ascii "null" (00)i character, 
hence the definition name NULL , The Name Field of NULL actually contains an ascii null, so when the end of a buffer is encountered, 
-FIND "searches the dictionary for NULL and executes it. NULL drops the top value from the return stack and then returns to tne 
definition following INTERPRET ; not back to INTERPRET . 

The reason why the user variable STATE contains a COH to denote compilation mode is covered in the deception of ] . 

* At entry - No stack parameters but the text input must be formatted such that tokens (words) are separated by blanks. 
Buffers must be terminated with ascii nulls (00). 


* At exit - No parameters. 

LIKELY ERROR. MESSAGES: 

? pronounced "HUH"? (0) — The word in question cannot be found in the dictionary and is not a number. 

EMPTY STACK (1) — More values have been removed from the parameter stack than were added. 

FULL STACK (7) — Too many values have been added to the parameter stack. 

INTERPRET is a high level colon definition. 

Refer to WORD , -FIND , NULL (or X ), DPL , QUIT , LOAD , and ] . 

FORTH-79: INTERPRET is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". 

Definition: : INTERPRET ( —) 

BEGIN 

-FIND IF 

STATE (a) < IF 

CFA , 

ELSE 

CFA EXECUTE 
THEN 

?ST ACK 

ELSE 

HERE NUMBER DPL (a) 1+ IF 

[COMPILE] DLITERAL 

ELSE 

DROP [COMPILE] LITERAL 
THEN 

? ST ACK 

THEN 203 


AGAIN 



DOCOL 

BEGIN 
. ( iNTEl ) 

-FIND 



Figure INTERPRET-1 
High Level Flow Chart of INTERPRET . 


^ INTERPRET ^ 


STATE 


(Run time portion of 
: ) Save IP and 
start interpreting 
this definition. 

_ .. ^- 



Search both the 
CONTEXT and 
CURRENT vocabu¬ 
laries for a Name 

Field match with 
the next word in the 
input stream. 

Is 

truth 
\= 0 

1 

\ Y 

flag - 

N 


Entry point for the 
branch from the 
AGAIN. 

Determine if the next 
input stream word 
should be treated 
like a definition or a 
number. 

Try to locate the word 
in the dictionary. 
Leave a true flag (1) 
if found. 


fa! 


-^(lNTE2) 


Branch if the word was 
not found. Attempt to 
treat it as a number. 

The word was found in 
J the dictionary. Now 
^ determine if it should 
be compiled or 
executed. 



Set up for |a) . The 
contents of STATE 
reflect what "state" 
the system is in. 

For 8080 fig-FORTH 
Version 1.1: 

00 = Interpreting 
CO = Compiling 


Set up for < . 


If the length byte (put 
on the stack by -FIND ) 
of the definition is 
less than STATE , the 
word should be 
compiled. This works 
because a value of COH 
in STATE denotes 
compiling state. If the 
length byte has its 
precedence bit set (i.e., 
is IMMEDIATE ); 
it will have a value 
greater than COH and 
will therefore always 
be executed. 
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EXECUTE 


i.e., The "precedence 
bit" and the "beginning 
of Name Field bit" 
together equal CQH. 
Since a name has a 
length of at least 1 , 
the length byte will 
always be at least C1H; 
therefore, it will 
always be greater than 
COH and its definition 
will always be 
executed—even when 
the system is in compile 
state. 

If ST ATE equals 0 

f i —» « V 

ViiiLCipiCL ouatcyj w ic 

"Name Fieid bit" and 
the length together are 
always larger than 0 
and every definition 
will be interpreted. 


F 


CFA 



ELSE 


.(Wo)- 


CFA 


Replace the PFA on 
the top of the 
parameter stack with 
the CFA of that same 
definition. 



Branch if the word is 
to be executed and not 
compiled. 



Set up for ,. A word 
is compiled by storing 
its Code Field Address 
(CFA) into the 
dictionary. 


"Compile" the named 
definition. 



Have executed the "true 
portion" of the IF 
structure; now branch 
around the "false 
portion". 


This is the entry point 
for the "false portion" 
of the previous IF . 

(i.e., The word is to 
be "executed"; and, not 
"compiled".) 


Set up for EXECUTE . 
EXECUTE expects the 
CFA of the definition to 
execute to be on the 
top of the parameter 
stack. 


"Execute" the 
definitions whose 
CFA is on the top of 
the parameter stack. 


i.e., Interpret the 
command in the input 
data stream. 


< 


NOTE: This is where 
words entered from the 
terminal are executed 
as well as non-compiled 
words from LOAD 
screens. Also 
IMMEDIATE words 
are executed here. 
Including NULL 
(or X) which drops the 

fork onfnu nff fho 
w 

return stack thereby 
causing control to 
return where the second 
return stack entry 
points and NOT to the 
7STACK which follows. 




THEN 
. (iNTE^ 


7STACK 




Issue Errc 
1 (EMPTV 
and QUIT 
underflow 
occurred; 
Message ' 
STACK) 
if overflo 
occurred. 

>r Message 
STACK) 
if stack 
has 

Error 
(FULL 
ind QUIT 
w has 



[Branch. 

1 ___ 


This is the entry point 
from the ELSE portion 
of the previous IF . 
i.e., The word was 
compiled and the 
EXECUTE portion was 
then branched around. 


NOTE: This is the only 
place during normal 
execution that the 
"system" checks the 
stack. (The stack is 
also checked if the 
value is a number.) It 
is possible for the 
stack to get far out of 
bounds before ever 
reaching here. 



j—jow 0 ©Xscutsd the **trus 
portion" of the IF 
structure because the 
word was found in the 
dictionary; now, branch 
around the "false 
portion". 


ELSE Entry point for the 

"false portion" of the 
previous IF structure 
that tested to see if 
-FIND found the word in 
the dictionary. 


.(lNTE2) 


HERE 


The word is not in the 
< dictionary. See if it ^ 
j can be converted into a j 
number. 

1 _ 

Place the address of 
the next available 
dictionary location 
onto the top of the 
parameter stack. 


HERE also points to the 
length byte of the word 
being interpreted 
( WORD moved it to 
PAD from the TIB ). 
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NUMBER 


[COMPILE ] 


DPL 


@ 


1 + 


F 



This will convert the 
character string to a 
number if possible. If 
invalid numeric 
characters are present, 
a "?" will be output. 
i.e., The input is 
neither a valid 
definition nor a valid 
number. 


The characters are a 
numeric value. 
Determine whether to s. 
treat it as a single or 
double precision value. 


Set up for (a) . DPL is 
set by number to 
reflect the character 
position of an 
encountered decimal 
point (meaning in this 
case — double 
precision). It is set 
to -1 if no decimal 
point is encountered. 


Set up for 1+ . Fetch 
the contents of DPL . 


Convert the contents of 
DPL into a truth flag. 

If no decimal point was 
found, DPL is set to 
-1. Adding 1 to that 
makes 0 (a false flag). 
Adding 1 to a 
character position 
results in a non-zero 
true flag. _ 



Branch if adding 1 to 
the contents of DPL 
equaled 0. i.e., No 
decimal point was 
found. 


DLITERAL 



Have executed the "true 
portion" of the IF 
structure (the value 
was double precision). 
Now branch around the 
"false portion". 


ELSE 



DROP 


\ 

1 

Drop the to 
off the para 
stack. 

p value 
meter 

-— 


This is the entry point 
for the "false portion" 
of the previous F 
structure. 


{ The value is single 
precision. 


1} 


The value is only 
single precision, so 
drop the high order 
word. 


[COMPILE ] 


Force compilation of 
the following 
IMMEDIATE word. 


Since LITERAL is an 
IMMEDIATE word, 
[COMPILE ] must be 
used to compile it into 
the definition. 
(Otherwise it would 
execute instead of being 
compiled.) [COMPILE] 
is only used to "compile" 
LITERAL into 
INTERPRET 
(at Sequence 1) and 
does not exist in 
INTERPRETS definition 
when INTERPRET is 
executed at compile 
time (at Sequence 2). 
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INTERPRET is an 
"infinite" loop that is 
only exited by 
encountering a null 
character, executing 
NULL and "tricking" 
NEXT to cause an exit 
from the routine. (See 
NULL and NEXT .) 






IP 


IP 

IP is a pointer used by FORTH's "threading" words. It plays an important role in such words as NEXT , ;S , DOCOL (the execution time 
portion of :), etc. 

IP generally serves as a pointer to the next "word" (actually a CFA within the Parameter Field of a definition! tn execute. NEXT i.jmn* 
indirectly "through" this pointer to execute the Code Field procedure. J r 

IP is not a true FORTH word. It is not a variable. It is a logical entity and may be physically kept in registers or memory or whatever 
depending upon the exact system implementation. 

In the 8080 fig-FORTH Version 1.1, IP is contained in the register pair BC. 

Refer to NEXT , : , ;S , DOES> , and EXECUTE . 
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KEY ( — input value ) 

KEY inputs a character from the terminal and places it onto the top of the parameter stack. 


KEY 


i\ju 11 : Control is not returned from KEY until an input character is available. If processing must be performed 
input character, 7TERMINAL may be used to determine if input data is actually present before invoking KEY. 


The actual operation of the word is installation dependent. 


EXPECT is an example of a word which uses KEY . 


* At entry - No parameters. 

* At exit -The top of the parameter stack contains a 16-bit value of which the low order portion is the 8-bit value input 
from the terminal. 


KEY is a low level code primitive. 

Refer to 7TERMINAL . 

FORTH-79: The FORTH-79 equivalent for KEY is KEY . 


(ED 


8080 fig-FORTH 
Version 1.1 


Wait until 
character 
available. 

_ 

an input 
is 



Read char 
place it or 
stack. 

acter and 
to top of 


NEXT 






LATEST 


LATEST ( — address ) 

LATEST places the Name Field Address of the bottom-most word in the CURRENT vocabulary onto the top of the parameter stack. 
When compiling, this bottom-most word is also the "latest" or most recently compiled definition. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the Name Field Address of the topmost word in the CURRENT 
vocabulary. 

LATEST is a high level colon definition. 

Refer to CURRENT , and VOCABULARY . 

FORTH-79: There is no FORTH-79 eguivalent for LATEST . 

Definition: : LATEST ( — address) 

CURRENT (3 fa) ; 


DOCOL 


CURRENT 


i 


@ 


;s 



Get the contents of 
CURRENT. CURRENT 
points to the vocabulary 
pseudo link field. 


Pick up the contents of 
the vocabulary pseudo 
link field. The 
vocabulary pseudo link 
field points to the 
"latest" definition 
added to the "current" 
vocabulary. 
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LEAVE ( - ) 


LEAVE 


LEAVE is used to prematurely exit a OO-LOOP. It forces termination of the loop by setting the Limit value equal to the current value of 
the Index which in turn causes an exit at the next execution of LOOP or +LOOP . The Index value remains valid and unchanged. 

Note that the fact that the Index and Limit values are kept on the return stack is an installation dependent choice. (Refer to I). 

INDEX is an example of a word which uses LEAVE to prematurely exit a DO-LOOP structure. 

* At entry - No parameter stack entries. 

* At exit - No parameter stack entries. 

LEAVE is a low level code primitive. 

Refer to DO , LOOP , +LOOP , (LOOP) , (+LOOP) , and I . 

FORTH—79s The FORTH-79 equivalent for LEAVE is LEAVE . 



NEXT 
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LFA 

LFA ( Parameter Field Address — Link Field Address ) 

LFA (pronounced "L-F-A") converts a given Parameter Field Address of a dictionary definition into its Link Field Address. 

The structure of the header of a FORTH definition is: 

Name Field Variable length 

Link Field 2 byte address pointer 

Code Field 2 byte address pointer 

Parameter Field Variable length 


An example of the use of LFA can be found in the word ID. . 


* At entry - The top of the parameter stack contains the Parameter Field Address of a FORTH definition. 

* At exit - The top of the parameter stack contains the 16-bit Link Field Address of the specified FORTH definition. 
LFA is a high level colon definition. 

Refer to NFA , CFA , and PFA . 


FORTH-79: There is no FORTH-79 equivalent for LFA . 

Definition: : LFA (PFA —LFA) 

04 - ; 


DOCOL 


LIT 
04 H 


;S 



Decrement the PFA by 4 
(now aiming at the Link 
Field). 
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LIMIT 


LIMIT ( — address ) 

LIMIT is a single precision CONSTANT value. This constant places the memory address of the next memory location past the end of the 
last or highest (hence " LIMIT ") block buffer in the buffer-array onto the top of the parameter stack. Refer to +BUF for an example of 
the usage of LIMIT . Also see BLOCK and BUFFER for descriptions of the buffer-array. 

Conversely, FIRST is the constant that reflects the lowest (hence " FIRST ") buffer-array address. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the signed 16-bit memory address of the next memory location after the 
end of the last block buffer in the buffer-array. 

Refer to +BUF , BLOCK , BUFFER , and FIRST . 

FORTH-79: There is no FORTH-79 eguivalent for LIMIT . 
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LIST 

LIST ( Screen number — ) 

LIST "lists" a specified screen onto the output device. The value of the constant C/L (Characters per Line) determines the length of an 
editing screen line. A screen is usually divided into 16 lines of 64 characters each. 

The basis of LIST is a DO-LOOP which uses the loop Index as an input to .LINE . 

TRIAD is an example of a word which uses LIST . 


* At entry - The top of the parameter stack contains the unsigned 16-bit screen number to be listed. 

* At exit - No parameters on the stack. However, the user variable SCR now contains the screen number that was listed. 
LIST is a high level colon definition. 

Refer to C/L , and B/SCR . 


FORTH-79: The FORTH-79 equivalent for LIST is LIST . 


NOTE: The 8080 fig-FORTH Version 1.1 has been changed to stop listing if a key is pressed, 
logic of LIST according to the fig-FORTH Model. 

Definition: : LIST ( screen number --) 

DECIMAL CR DUP SCR I ." SCR" . 10 0 

DO 

CR I 3 .R SPACE I SCR fa! .LINE 
LOOP CR : 


The following flowchart shows the main 


DOCOL 


DECIMAL 


CR 


DUP 


SCR 


." SCR # " 



fig-FORTH 

Model 


LIT 

10H 


Make sure system is in 
base 10. 


(DO) 


DO 


Duplicate the screen 
number to list. Set up 
for 1 . 


SCR is used to hold the 
screen number of the 
last screen listed. 
Editor commands then 
reference SCR . 


Set SCR to this screen. 


](W> 


CR 


Print the screen number 
being listed. 



Place the literal 
value 10H onto the 
top of the parameter 
stack. 




Place the constant 
value 0 onto the top 
of the parameter 
stack. 




Move loop control 
characters (Index 
and Limit) to the 
return stack. 





Output a carriage 
return and linefeed 
to the output 
device. 




Copy the Loop Index 
onto the top of the 
parameter stack. 

_ 1 


Place the 
value 3 on 
of the pars 
stack. 

constant 
to the top 
i me ter 


Set up Limit value for 
DO . Loop through the 
DO-LOOP 16 times (i.e., 
print 16 lines). 


Set up initial value 
for DO loop. 


This execution time 
portion of DO is 
compiled into this 
definition by DO (at 
LIST's Sequence 2). 


This is the entry point 
for the jump from the 
LOOP portion of this 
DO-LOOP structure. 


I Output one line of text 
< preceded by the line 
I number. 


3 


{ Print the line number^ 
being listed. 


J 


In this case, the Loop 
Index equals the line 
to be printed. 


Set up field width for 
.R . 
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.R 


SPACE 


I 


SCR 


.LINE 


(LOOP) 


LOOP 


CR 


;S 
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LIT 


LIT ( — literal value ) 

LIT places the 16-bit contents of the next dictionary location onto the top of the paramter stack. LIT , followed by the literal value, is 
compiled into a definition by LITERAL and DLITERAL . LIT , then, is the execution time (Sequence 3) action of LITERAL and 
DLITERAL . 

* At entry - No stack parameters although the desired literal value must reside in the next dictionary entry. 

* At exit - The top of the parameter stack contains a 16-bit value equal to that contained in the location following LIT . 

LIT is a low level code primitive. 

Refer to LITERAL , and DLITERAL . 

FORTH-79: There is no FORTH-79 equivalent for LIT . 



HPUSH Push literal data onto 

stack. 


NEXT 


NOTE: In fig-FORTH, 
PUSH , PUT , and NEXT 
are contained in LIT . 
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LITERAL 


LITERAL 


COMPILE TIME (Sequence 2): ( value — ) 

EXECUTION TIME (Sequence 3): ( — value ) 

LITERAL is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution 
time. 


Although LITERAL has no effect (Sequence 2) if not used within a colon definition, it does not signal an error. The compile time action 
of LITERAL is to compile a dynamically calculated 16-bit value into a definition. The end result of the compile action here is the same 
as LIT . LIT is compiled into a definition "automatically" (in the Interpreter) by the presence of a 16-bit numeric value in the input 
stream. However, if this numeric value is calculated dynamically during compilation, it will not exist in the input stream and therefore 
some other method must be used to compile LIT and the value into the dictionary. LITERAL is this other method. 


An example of the use of LITERAL would be calculating the length of a table to be ERAS Ed * This calculation will be performed only 
once, at compile time instead of each time the table is erased. In this example, TABLE-LEN and //-OF-ENTRIES , when multiplied 
together, give the number of bytes to erase. This sample definition would look like this: 


: ERASE-TABLE BEG-TABLE-ADDR [ TABLE-LEN //-OF-ENTRIES * ] LITERAL ERASE ; 

[ stops compilation, TABLE-LEN and //-OF-ENTRIES are multiplied, and their product is left on the stack. ] resumes compilation and 
LITERAL then compiles the value into the definition. 

The execution time action of LITERAL is that of LIT . That is, upon execution of LIT, the 16-bit value is placed on the top of the 
parameter stack. 

Note that LIT is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 


COMPILE TIME (Sequence 2)z 

* At entry - The top of the parameter stack contains a signed 16-bit single precision value to be compiled into the 
definition. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - No parameters. 

* At exit - Tne top of the parameter stack contains the signed 16-bit single precision value previously compiled into the 
definition being executed. 

LITERAL is a high level colon definition. 

Refer to LIT , [ , J , and INTERPRET . 

FORTH-79: The FORTH-79 equivalent for LIT is LIT . 

Definition: : LITERAL ( value --) ( compile time) 

STATE (3 IF COMPILE LIT , THEN ; IMMEDIATE 
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COMPILE TIME action of LITERAL (Sequence 2): ( value — ) 




Entry point from the 
false branch of the 
previous IF . IP was 
not compiling so branch 
here and exit. 


IMMEDIATE 


Set the precedence 
bit of this 
definition so it 
will be executed at 
compile time and not 
compiled into the 
definition. 


LITERAL is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


EXECUTION TIME action of LITERAL (Sequence 3): ( — value ) 

The EXECUTION time action of LITERAL is that of LIT . 
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LOAD 


LOAD ( screen number — ) 

LOAD begins interpretation of the source text from the screen number specified on the top of the parameter stack. The blocks that 
comprise the specified screen are read from mass storage to memory (if they are not already in the buffers) and interpreted. 

LOAD starts an entirely new interpretation, level; therefore LOADs may be nested . Loading terminates upon encountering a null (0) or at 
;S . A null or ;S will pop back up to the previous level, and resume interpretation after the word that caused LOAD to be executed. 

Note: "0 LOAD" will cause a return stack overflow and a system crashl 

As a matter of programming style, it is often desirable to create a "load screen" which specifically loads each screen via LOAD (with 
each LOAD followed by a comment describing the screen to be loaded) rather than loading multiple screens via —> . This makes it much 
easier to keep track of what is being loaded. 

* At entry - The top of the parameter stack contains a 16-bit unsigned number specifying the screen to "load" and 
interpret. 

* At exit - No parameters. 


LOAD is a high level colon definition. 


Refer to , WORD , and INTERPRET . 


FORTH-79: The FORTH-79 eguivalent for LOAD is LOAD . 


Definition: 


DOCOL 


BLK 


(§ 


>R 


IN 


@ 


LOAD ( screen 

BLK fa) >R 

number — ) 
IN fa) >R 

0 IN 1 B/SCR * 

BLK 

INTERPRET 

R> IN 1 

R> BLK 1 ; 




BLK contains the block 
number currently being 
interpreted. A zero 
denotes terminal input. 


Set up for >R . Pick up 
the contents of BLK . 


Save the block number 
currently being 
interpreted on the 
return stack. This 
makes nested load 
screens possible. 


Set up for fa) . IN 
contains the offset in 
the current block of 
the next word to be 
interpreted. 

Set up for >R . Pick up 
the contents of IN . 


>R 


0 


IN 


B/SCR 


* 



Save the location of 
the next word to be 
input by WORD and 
interpreted. This (plus 
the previously saved 
block number) makes 
nested load screens 
possible. _ 


Set up for 1 . 


Initialize IN to 0 so 
interpretation will 
begin with the first 
character of the block. 


fc 


n 


Calculate the block 
] number to interpret.] 


By convention a screen 
is 1024 bytes long. The 
number of physical disk 
blocks (or sectors) 
composing a screen 
varies with each 
system. 


Multiply the number of 
physical blocks per 
screen by the screen 
number (which was 
passed as a parameter 
to LOAD). 
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BLK 


INTERPRET 


R> 


IN 


R> 


BLK 



Set up for I . 


Store the calculated 
physical block number 
on which to begin 
interpreting. 


BLK contains the block 
number to begin 
interpretation from. 
INTERPRET will read in 
and interpret this 
block and all of the 
other remaining blocks 
on the specified 
screen. Note: 
INTERPRET can 
execute other LOAD 
commands thereby 
"nesting" LOAD's. 


Retrieve the previously 
saved value for IN . 


Set up for 1 . 


Restore the pointer to 
the next word to be 
interpreted. i.e., 
"Un-nest". 


Retrieve previously 
saved value of BLK . 


Set up for 1 . 


Restore the block 
number previously being 
interpreted, i.e., 
"Un-nest". 
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LOOP 


LOOP 


COMPILE TIME (Sequence 2)i ( loop address \3 — ) 


EXECUTION TIME (Sequence 3): ( - ) 


LOOP is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution 
time. 

LOOP is used to end a DO-LOOP structure in conjunction with the word DO . The compile time action of LOOP is to compile the run 
time word (LOOP) into the dictionary. Secondly, it resolves the "loop body" entry point address provided by DO into a return branch 
offset used by (LOOP) and stores this offset into the dictionary. LOOP must only be used within a definition. Some compiler security is 
provided by checking for a 3 on the top of the stack. Since DO leaves a 3 on the stack at compile time (Sequence 2), an un-matched DO 
and LOOP will probably not have a 3 on the top of the stack and the error will be detected. 


The apparent run time action (Sequence 3) of LOOP is to increment the loop Index by one and compare this new Index value with the 
Limit value. NOTE: This action is actuaiiy performed by (LOOP) at run time. If the Index value is less than the Limit value, a branch 
back to the "loop body" of the DO-LOOP structure is executed. If the Index is equal to or greater than the Limit, then both of these 
values are dropped from the return stack and interpretation continues with the definition following LOOP . 


DO - LOOP structures must be used within a colon definition. 


Note that LOOP is an IMMEDIATE word. This means that its precedence bit is set, and it will therefore execute at compile time. 


If ai increment value different than 1_ is needed, +LOOP should be used. 


VLIST is an example of a word which uses LOOP . 


COMPILE TIME (Sequence 2h 

* At entry - The top of the parameter stack contains the 16-bit single precision value 3 used to provide compiler security. 

(The value 3 is left on the stack at compile time by DO .) The second stack entry contains a 16-bit address specifying the 
entry point of the DO portion (i.e., the beginning of the "loop body") of the DO-LOOP structure. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - (LOOP) uses no input values from the parameter stack but does expect the Index and Limit values to be on the 
return stack. 

* At exit - (LOOP) drops both the Index and Limit values from the return stack when the DO-LOOP structure is exited. 

(Refer to (LOOP) .) 

LIKELY ERROR MESSAGES: 

COMPILATION ONLY (11H) — This word may only be used within a colon definition. 

CONDITIONALS NOT PAIRED (13H) - There is some sort of problem with the pairing of conditionals within the definition being 
compiled. 

LOOP is a high level colon definition. 

Refer to (LOOP) , DO , +LOOP , and (DO) . 

FORTH-79: The FORTH-79 equivalent for LOOP is LOOP . 

Definition: : LOOP ( Loop address\ 3 — ) ( compile time ) 

3 7PAIRS COMPILE (LOOP) BACK ; IMMEDIATE 
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COMPILE TIME action of LOOP (Sequence 2): ( loop address\ 3 — ) 


DOCOL 


3 


7PAIRS 


COMPILE 


(LOOP) 


BACK 


;s 


IMMEDIATE 



Set up for 7PAIRS . 


A LOOP with a 
corresponding DO will 
result in a 3 on the 
stack. An error message 
will be issued and QUIT 
will occur if not. 


This puts (LOOP) into 
the definition being 
compiled. 


(LOOP) is compiled into 
the definition. It is 
not executed at compile 
time. 


The address left by DO 
is used to calculate a 
return branch offset. 
This offset is then 
compiled into the 
definition and 
referenced by (LOOP) at 
execution time. 


LOOP is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


EXECUTION TIME action of LOOP (Sequence 3): ( - ) 

The execution time of LOOP is actually that of (LOOP) . 
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v , M* 

M* ( value 1 \ value 2 — double product J 

M* (pronounced "M-star") multiplies two signed single precision values and replaces them with their signed double precision product. 

The heart of M* is U* (unsigned multiply). The first part of M* determines the eventual sign of the product, then the unsigned 
multiplication of U* is performed, and lastly the sign is applied to the product. 

* At entry - The top two entries on the parameter stack contain signed 16-hit values to be multiplied together. 

* At exit - The top two entries of the parameter stack contain a 32-bit signed double precision product. The top entry 
contains the signed high order portion of the product. The second stack entry contains the low order portion of the 
product. 

M* is a high level colon definition. 

Refer to U* . 


FORTH-79: There is no FORTH-79 eguivalent for M* 


Definition: 


DOCOL 


OVER 


OVER 


XOR 


>R 


ABS 


M* ( value l\ value 2 \value 2 — double produce ) 

OVER OVER XOR >R ABS SWAP ABS U* 


SWAP 


R> D+- 



ABS 


The logical result of 
the XOR follows the 
sign rules of 
multiplication. 


Set up for XOR . 


Set up for XOR . 

( OVER OVER can be 
replaced by 2DUP .) 


Determine the sign of 
the product and save 
it. 


Save the sign of the 
product to be used 
later. 


I Make both values! 
l positive. 

Set up for 
multiplication by 
getting rid of any 
negative sign bits. 


U* 


R> 


D+- 


;S 



Set the second value up 
for ABS . 


Set up for 
multiplication by 
making both values 
positive. 


{ Perform the 
multiplication 


3 


Multiply the two values 
leaving a double 
precision result. 

Warning: U* does not 
correctly multiply 
unsigned 16-bit 
numbers. It requires 
positive signed 
16-bit numbers to 
multiply correctly. _ 


I Apply the appropriate) 
j sign to the product 


ateI 


Set up for D+- . 
Retrieve the previously 
calculated product 
sign. 


Apply the previously 
calculated sign to the 
product. 
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Ml 


M/ ( double low \ double high \ divisor — remainder \ quotient) 

M/ (pronounced "M-slash") divides a 32-bit signed double precision value by a 16-bit signed single precision value and replaces them with 
a 16-bit signed remainder and a 16-bit signed quotient. 

The remainder takes its sign from the dividend. 


Note that M/ uses a double precision dividend while /MUD uses a single precision dividend. 

The heart of M/ is U/ (unsigned divide). The first part of M/ saves the signs of the dividend and divisor, then makes the inputs to U/ 

positive. After the division, the signs of the quotient and remainder are determined. 

* At entry - The top of the parameter stack contains a 16-bit signed single precision divisor. The second and third stack 
entries contain a 32-bit signed double precision dividend. The second stack entry contains the high order portion of the 
dividend; the third, the low order portion. 

* At exit - The top of the parameter stack contains the 16-bit signed single precision quotient. The second stack entry 
contains the 16-bit signed single precision remainder. 

M/ is a high level colon definition. 

Refer to U/ . 


FORTH-79: There is no FORTH-79 equivalent for M/ . 


Definition: 


DOCOL 


OVER 


>R 


>R 


DABS 


M/ ( double low\ double high\ divisor -- remainder\quotient) 
OVER >R >R DABS R ABS U/ R> R XOR +- 

SWAP R> +- SWAP ; 



R 


ABS 


U / 


R> 


R 



Set up for U/. Get a 
copy of the divisor 
from the return stack 
so can divide with it. 


U/ requires an unsigned 
divisor. 



Perform the division 
leaving the unsigned 
quotient on the top of 
the unsigned remainder. 



Set up for XOR . 
Retrieve the previously 
saved divisor. 


Set up for XOR . Now 
get a copy of the 
sign portion of the 
dividend. 
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XOR 


SWAP 


R> 


SWAP 
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M/MOD 

M/MOD ( double dividend \ divisor — remainder \ double quotient) 

wilh?Ii!^? U J! i n" l ™l Sh "' r ' 0d " ) dl - Vl ? S a "r i9ned “““A 16 preclslon value * an uns ‘9™« single precision value and replaces them 
with the unsigned single precision remainder and the unsigned double precision guotient. 

U/ is the basis for M/MOD; but, since the output of U/ is only a single precision quotient, some special ODeratinns are nece^*™. Tn rhie 

dfvTHe^renTe^hfif 80 ^ 6 ^ a mannersimilar to performing long division by hand. i.e., The high order portion of the dividend is 

n V f q f UOt ‘ ent and a remainder. This remainder and the low order dividend are again divided, rendering the rest 

of the double precision quotient and a remainder. ’ imy u.o icoi 


uIldersta^^oD^r V ^ /M ° D * C ° nfUSing en0Ugh that a Step by step Ascription of the effect of each word is necessary to properly 


Divisor 

Dividend H 
Dividend L 

Dividend H 
Dividend L 

0 

Dividend H 
Dividend L 

Divisor 

0 

Dividend H 
Dividend L 

Parameter 
* Stack 


>R 

0 

R 1 

Word 


Divisor 

Divisor 

Divisor | 

Return Stack 


Quotient H 
Remainder 
Dividend L 

Divisor 

Quotient H 
Remainder 
Dividend L 

Quotient H 
Divisor 
Remainder 
Dividend L 

Divisor 
Remainder 
Dividend L 

\ 

Parameter 
* Stack 

u/ 

R> 

SWAP 

>R 1 

Word 

Divisor 



--- J 

Quotient H 1 

> Return Stack 



Quotient L 
Remainder 

Quotient H 
Quotient L 
Remainder 



Parameter 

L Stack 

u/ 

R> 


1 

Word 

Quotient H '"j 

Return Stack 


At entry - The top of the parameter stack contains a 16-bit unsigned single precision divisior. The second and third stack 
entries contain a 32-bit unsigned double precision dividend, with the high order portion of the dividend in the second stack 
entry and the low order in the third. 

At exit - The top two entries of the parameter stack contain a 32-bit unsigned double precision quotient. The top entrv 
contains the high order portion of the quotient. The second stack entry contains the low order portion of the quotient, 
i he third stack entry contains the 16-bit unsigned single precision remainder. 

M/MOD is a high level colon definition. 

Refer to U/ . 


FORTH-79: 

Definition: 


There is no FORTH-79 equivalent for M/MOD . 

: M/MOD ( double dividend \ divisor — remainder \ double quotient) 

>R 0 R U/ R> SWAP >R U/ R> ; 
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DOCOL 


>R 


0 


R 


U / 


R> 


SWAP 


>R 


U/ 


R> 



Save the divisor on the 
return stack for second 
U /. 


Set up for U/ . Make 
high order dividend 
into double precision. 


Set up for U/ . Get a 
copy of the divisor. 


Divide the high order 
dividend and leave a 
single quotient and 
remainder. 


Get the divisor. 


Set up for >R . Swap 
the divisor with the 
high order quotient. 


Save the high order 
quotient on the return 
stack. 


Now divide the 
remainder and low order 
dividend. 


Put the high order 
quotient back onto the 
parameter stack. 


;S 


(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 

oglli nn r> «r\n mn 

udm i iy uuuuui C* 
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MAX 


MAX ( value \value — maximum value ) 

MAX (pronounced "max") compares the top two 16-bit signed values on the parameter stack, drops the smaller of the two values, and 
leaves the larger (or MAXimum). 

MIN performs the opposite function of MAX . 

SPACES is an example of a word which uses MAX . 


* At entry - The top of the parameter stack contains one of the 16-bit signed single precision values to be compared. The 
second stack entry contains the other 16-bit signed single precision value to be compared. 

* At exit - The top of the parameter stack contains the larger of the two 16-bit values. 

MAX is a high level colon definition. 

Refer to MIN . 


FORTH-79: The FORTH-79 equivalent for MAX is MAX 


Definition: 


MAX ( value\ value -- maximum value ) 

OVER OVER < IF SWAP THEN 


DROP 



DROP 


;s 



Drop the smaller entry 
from the parameter 
stack, leaving the 
larger entry. 
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MESSAGE 

MESSAGE ( message number — ) 

MESSAGE outputs a selected message to the output device. The message can either be just a message number (if the contents of the 
user variable WARNING is a 0) or it is a line ot text (if the contents of WARNING is a non-zero value). 

The message number is supplied as a sjaned single precisian value. When WARNING contains .1, this «mher is t«d as a line.offset 

relative to Line fl of Screen A in Drive 0. That is to say that a message number of +2 will cause ..me 2 on Scre.n A ... be <xitou„ A value 

of +19 will cause Line 3 of Screen 5 to be output. A value of -1 will cause Line 16 of Screen 3 to be output. 

Message Number 0 will not output anything as Line 0 of Screen 4 is a comment. Note that an Error Message Number 0 input to ERROR 
causes a ? ("HUH?") to be printed. 

All relative message text lines are based on Line 0 of Screen 4 in Drive 0. MESSAGE adjusts its input to .LINE by what is in OFFSET so 
all references are always relative to Drive 0. 

Note that, while the FORTH system uses MESSAGE for error messages, its use is not restricted to that purpose. Applications may use 
the word to output any manner of desired messages stored anywhere on disk. 

It is a good idea to always reserve the error message screens for error messages on ail disks, e.g., A data disk that has ai data file in !the 
location where error messages are kept will cause undetermined garbage to be displayed if an error occurs and MESSAGE outputs a 
message from what it "considers" to be valid error message text. 

* At entry - The top of the parameter stack contains a signed 16-bit single precision message number. 

* At exit - No parameters. 

MESSAGE is a high level colon definition. 

Refer to WARNING , ERROR , .LINE , OFFSET , and BLOCK . 

FORTH-79: There is no FORTH-79 equivalent for MESSAGE . 


Definition: 


MESSAGE ( # - ) 

WARNING (a) IF 


-DUP IF 

4 

THEN 
." MSG " . 


OFFSET fa) B/SCR / - .LINE 


DOCOL 


WARNING 


MESSAGE 


(Run time portion of 
:) Save IP and 
start interpreting 
this definition. 


Place the address of Set up for !§ . If 
the user variable WARNING contains a 

WARNING onto the top zero, only the error 
of the stack. message number is to be 

I displayed. 


Replace the address 
on the top of the 
parameter stack with 
the memory contents 
of that address. 


^ Is \ 
truth flag 
^ = 0 ? . 


Set up for IF . Fetch 
the contents of 
WARNING . 




Duplicate the top 
value on the 
parameter stack only 
if it is non-zero. 




^ Is ^ 
truth flag 
^ = 0 ? ^ 


Branch if the contents 
of WARNING is 0 (i.e., 
only display the 
message number). 


WARNING contained a 
non-zero value. 

Display the message 
line relative to Screen 
4 Line 0. 


Set up for IF . The IF 
will use the message 
number as a truth flag 
so duplicate it so 
there will be a message 
number available for 
the "true portion" of 
the F structure. 


-^(messz) 

Branch if message 
number is 0 because 
there is no error 
message on Line 0 of 
Screen 4. 


Calculate the absolute 
screen number of Screen 
4 taking into account 
any offset value that 
may be in OFFSET . 

NOTE: This does not 
calculate the screen 
number where the 
message resides. .LINE 
performs that function. 
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LIT 

4 


OFFSET 


1 


B/SCR 


/ 


.LINE 


THEN 




■2H 


Set up for eventual - . 
4 is the screen number 
messages are referred 
to. 


NOTE: Message 
numbers are always 
relative to Drive 0 but 
since BLOCK uses the 
contents of OFFSET 
for explicit drive 
selection, we must take 
that into account here. 
Screen 4 is adjusted 
( subtracted) by the 
offset value. BLOCK 
can then add back the 
offset value and the 
end result is still 
Screen 4, Drive 0. 


Set up for / . Fetch 
the contents of 
OFFSET. 


Set up for / . B/SCR 
is a constant that 
reflects how many 
blocks a screen 
contains. 


Set up for - . Divide 
the value in OFFSET by 
blocks per screen to 
get how many screens 
(the value in OFFSET is 
in blocks) to adjust 
"Screen 4" by. 


Set up for .LINE . 
Adjust Screen 4 to 
reflect offset. 


.LINE will convert the 
message number (i.e., 
the relative line 
number) into an 
absolute line address 
relative to Line 0 of 
Screen 4 and print the 
appropriate message. 


This is the entry point 
for the "false portion" 
of the previous IF . 

i.e., The message 
number was 0 so no 
message is printed. 



Branch around the 
"false portion" of the 
IF structure. 


ELSE 



This is the entry point 
for the "false portion" 
of the previous IF that 
tested WARNING . 


The contents of 
J WARNING was 0, so 
j just output the message f 
I number. 


Output the message 
number. 


This is the entry point 
from the ELSE portion 
of the previous IF 
statement. 

i.e., After displaying 
the message, control 
skips over the "false 
portion" which only 
outputs the message 
number. 
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MIN 


MIN ( value \ value — minimum value ) 

MIN (pronounced "min") compares the top two 16-bit signed values on the parameter stack, drops the larger of the two values, and leaves 
the smaller (or MINimum). 

MAX performs the opposite function of MIN . 

CREATE is an example of a word what uses MIN . 

* At entry - The top of the parameter stack contains one of the 16-bit signed single precision values to be compared. The 
second stack entry contains the other 16-bit signed single precision value to be compared. 

* At exit - The top of the parameter stack contains the smaller of the two 16-bit signed values. 

MIN is a high level colon definition. 

Refer to MAX . 


FORTH-79: The FORTH-79 equivalent for MIN is MIN . 

Definition: : MIN ( value\ value -- minimum value ) 

OVER OVER > IF SWAP THEN DROP 


DOCOL 


OVER 


OVER 


IF 


SWAP 



DROP 


;S 



Drop the larger entry 
from the parameter 
stack, leaving the 
smaller entry. 


THEN 



This is the entry point 
for the THEN portion of 
the IF-THEN structure. 
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MINUS 


MINUS ( value to be negated — two's complement) 

MINUS replaces the 16-bit value on the top of the parameter stack with its two's complement. 

- is an example of a word which uses MINUS . 

* At entry - Tne top of the parameter stack contains the 16-bit single precision value to be converted. 

* At exit - The top of the parameter stack contains the 16-bit single precision two's complement of the given value. 
MINUS is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for MINUS is NEGATE . 



HPUSH Push complemented 

number onto the 
parameter stack. 


NEXT 
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MOD 


MOD ( dividend \ divisor — remainder ) 

MOD (pronounced "mod") divides a 16-bit signed single precision value by another 16-bit signed single precision value and replaces them 
with their 16-bit signed remainder (or modulo, hence the name MOD). The remainder takes its sign from the dividend. 

The basis of MOD is /MOD . /MOD leaves a quotient and remainder. MOD drops the quotient. This is very similar to / , which drops the 
remainder, 

* At entry - The top of the parameter stack contains the 16-bit signed single precision divisor. The second stack entry 
contains the 16-bit signed single precision dividend. 

* At exit - The top of the parameter stack contains the 16-bit signed single precision remainder. 

MOD is a high level colon definition. 


Kefer to /'MOu . 


FORTH-79: The FORTH-79 equivalent for MOD is MOD . 

Definition: : MOD ( dividend \ divisor--remainder ) 

/MOD DROP ; 


DOCOL 


/MOD 


DROP 



Perform the division 
and leave a remainder 
and quotient. 


Drop the quotient. 
Leave the remainder. 
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MON 

MON (-) 

MON (pronounced "mon") exits to the system monitor (hence "MON") of the system FORTH is running on (or under). The word may have 
other names (e.g., the 8080 1.1 CP/M Version uses BYE) but the function is always the same. 

* At entry - No parameters. 

* At exit - No parameters. 

MON may be a high or low level definition depending upon the specific installation. 

FORTH-79: There is no FORTH-79 equivalent for MON . 


1 

[mon) 



JMP 0 


8080 fig-FORTH 
Version 1.1 


Jump to the CP/M warm 
start vector. 
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NEXT 


NEXT 

NEXT is the FORTH inner interpreter. (Actually NEXT is the entry point label of the inner interpreter procedure.) This procedure is not 
a part of the FORTH dictionary. Its purpose is to sequentially execute the "next" Code Field Address contained within the Parameter 
Field of a compiled definition. 

NEXT only sequentially "executes Code Field Addresses"; it does not of itself perform any nesting or un-nesting. Nesting is performed 
via a word such as : ( DOCOL actually); un-nestinq is performed via a word such as ;S . 

All definitions must eventually be terminated with a jump to NEXT . Code definitions must end by directly jumping to NEXT or by 
performing the same function as NEXT (e.g., EXECUTE ). 

The action of NEXT can be symbolically described in high level terms as follows: 

IP !a) Fetch the contents of IP . ( IP points to the next CFA , i.e., "word", to execute.) 

fal W I Fetch the CFA IP is nolntino to and store it into W . 

2 IP +! Increment IP to point to the next "word" to execute. 

W fa) Fetch the contents of W . ( W now points to the Code Field of the defintion to be executed.) 

@ PC I Fetch the contents of this definition's Code Field (i.e., the address to execute) and put it into the CPU's 

program counter. 

Refer to W , IP , : , ;S , and DOES> . 


8080 fig-FORTH 
Version 1.1 



IP fa) fa) W I 
2 IP +'. 


IP now aiming at next 
dictionary entry. 



Entry point for NEXT1. 



W now aiming at Code 
Field Address of word 
to be executed, (i.e., 
aiming at "Y"). 

i.e., Pick up "Y" so 
program counter will be 
aiming at "Z". 
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NFA 


NFA ( Parameter Reid Address — Name Reid Address ) 

NFA (pronounced "N-F-A") converts a given Parameter Field Address ( PFA ) of a dictionary definition into its Name Field Address 
( NFA). 


The structure of the header of a FORTH definition is: 


Name Field 
Link Field 
Code Field 
Parameter Field 


Variable length 
2 byte address pointer 
2 byte address pointer 
Variable length 


* At entry - The top of the parameter stack contains the 16-bit Parameter Field Address of a FORTH definition. 

* At exit - The top of the parameter stack contains the 16-bit Name Field Address of the specified FORTH definition. 

CREATE is an example of a word that uses NFA . 

NOTE: Since the fig-FORTH Name Field is a variable length, a simple subtraction cannot be used to directly calculate its beginning 
address. TRAVERSE must be used instead. The exact nature of NFA may vary from system to system because of differing word sizes, 
etc. 


NFA is a high level colon definition. 
Refer to PFA , LFA , and CFA . 


FORTH-79: There is no FORTH-79 equivalent for NFA . A FORTH-79 program may not address into a definition's Name Field. 

Definition: : NF A (PFA — NF A) 

5 - -1 TRAVERSE ; 


DOCOL 


LIT 

05H 


LIT 

-1 


TRAVERSE 


;S 



Set up for subtraction. 


Aim at the last 
character of the Name 
Field. Set up for 
TRAVERSE . 


Set up for TRAVERSE . 
This is the direction 
indicator for 
TRAVERSE. The 
-1 causes a search 
direction from high to 
low memory. 


This will result in the 
beginning address of 
the Name Field being 
left on the top of the 
parameter stack. 
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NULL (- ) 


NULL 


NULL (pronounced "null" and sometimes called "X") is the word that causes an exit from the endless loop in the INTERPRET procedure. 
"NULL" is a pseudonym for an ascii null character (00). The actual Name Field of NULL consists of one ascii null character. 

Despite its rather non-standard name, NULL is a perfectly valid definition. That is to say that as INTERPRET sequentially moves 
through a buffer, compiling and interpreting as it goes, the end of the buffer will eventually be reached. By convention, all buffers must 
end with a null character. When INTERPRET encounters this null character, it searches the dictionary for a Name Field match. A 
match occurs when the null definition is encountered. Since NULL is a valid definition and is also IMMEDIATE , it is executed. 

NULL causes an exit from INTERPRET by dropping the top address of the return stack. Then, when NULL returns, it exits not to the 
level it was at (i.e., back to INTERPRET) but instead exits to one level of nesting higher (i.e., back to the definition that contained 
INTERPRET — more specifically to the definition immediately following INTERPRET .) For example, the word STATE in QUIT , or R> in 
LOAD . 

A large portion of the coding in NULL is devoted to checking to ensure that the system is not in compilation state if the null character 
encountered is at the end of an editing screen. (It must be determined if the current buffer is the iast buffer in a screen.) Tnis check is 
performed because it is illegal to extend compilation across editing screens. Error message 12H (EXECUTION ONLY) is issued if this 
condition is detected. 

Note that NULL is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 

* At entry - No parameters. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

EXECUTION ONLY (12H) — This word must not be used while the system is in compile mode. 

NULL is a high level colon definition. 

Refer to INTERPRET , QUIT , and LOAD . 

FORTH-79: There is no FORTH-79 equivalent for NULL . 

Definition: : NULL ( ) 

BLK fa) IF 

1 BLK +1 0 IN I BLK fa) B/SCR 1 - 

AND 0= IF 7EXEC R> DROP THEN 
ELSE R> DROP 
THEN ; IMMEDIATE 



level, i.e., Level that 
"called" INTERPRET . 


Figure NULL-1 

High Level Flowchart of NULL 
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DOCOL (Run time portion of 

:) Save IP and 
start interpreting 
this definition. 


Place the address of 
the user variable 
BLK onto the top of 
the parameter stack. 


Replace the address 
on the top of the 
parameter stack with 
the memory contents 
of that address. 


^ Is \ 
truth flag 
^ =0? . 


| Determine if 
l interpreting from disk. 


Set up for (al . BLK 
contains the block 
number currently being 
interpreted. 0 denotes 
terminal input. 


B/SCR 


Pick up the contents of 
BLK to determine where 
the input stream is 
coming from. 


^NULLy 

Branch if interpreting 
from the terminal. 


Interpretation input is 
from disk. Now 
determine if at the end 
of a screen. 


Store the specified 
value into the 
specified memory 
location. 


[ Place the address of 
the user variable 
BLK onto the top of 
the parameter stack. 


Replace the address 
on the top of the 
parameter stack with 
the memory contents 
of that address. 


Place the constant 
value B/SCR (blocks 
per screen) onto the 
top of the parameter 
stack. 


Place the constant 
value 1 onto the top 
of the parameter 
stack. 


Subtract the top 
stack entry from the 
second stack entry 
and replace the two 
values with their 
signed difference. 


Set IN to D. Set up to 
begin interpreting from 
the beginning of the 
next block. 


bet up tor (a) 


Set up for AND . Pick 
up the current block 
number + 1. 


Set up for - 


Set up for - 


Set up for AND . The 
purpose of subtracting 
1 from the bytes per 
screen is to make a 
mask for the following 
AND . 


Place the constant 
value 1 onto the top 
of the parameter 
stack. 


Place the address of 
the user variable 
BLK onto the top of 
the parameter stack. 


Add the specified 
16-bit value to the 
contents of the 
specified memory 
location. 


Place the constant 
value 0 onto the top 
of the parameter 
stack. 


Place the address of 
the user variable IN 
onto the top of the 
parameter stack. 


Set up for +1 . 


Set up for +1 . 


Set up for AND . 
Increment the current 
block number by 1 
(i.e., if it is the 
last block number in a 
screen, increment it to 
the beginning of the 
next screen.) 


Set up for 1 . 


Set up for I . IN 
contains a pointer to 
the character location 
being interpreted 
(relative to the 
beginning of the 



Logically AND the 
top two values on 
the parameter stack 
and replace them 
with the logical 
result. 


Replace the value on 
the top of the 
parameter stack with 
a true flag (1) if 
the value is zero; 
otherwise, replace 
the value with a 
false flag (0). 


This determines if the 
block number was the 
end of a screen. 

In this example, the 
numbers not enclosed in 
parenthesis are in 
decimal while the 
enclosed numbers are 
binary. 

If the block number was 
11 (1011), incrementing 
it by 1 gives 12 
(1100). If there were 4 
blocks per screen 
(0100), subtracting 1 
gives a mask of 3 
(0011) and ANDing 12 
and 3 (1100 and 0011) 
gives 0. Therefore no 
bits coincide, which 
means the block number 
was at the end of the 
screen. 

(This may not be the 
best way to do this, 
but it works.) 


Set up for IF . If it 
was at the end of a 
screen, we want to 
execute the "true 
portion" of the IF . 
Therefore, the truth 
flag must be reversed 


















IF 


?EXEC 


R> 


DROP 


THEN 


• (nULL2 }~ 




N 

Issue Error Message 
12H (EXECUTION 
ONLY) and QUIT 
if the system is 
not in EXECUTION 
state. 



Remove the top value 
of the return stack 
and place it onto 
the top of the 
parameter stack. 



Remove the top 
parameter stack 
entry from the 
parameter stack. 

— 



Branch. j- 


^ NULL3) 

Branch if not at end of 
a screen when 
encountered null. 


[Now test if compiling^ 

The whole purpose of 
the above decisions was 
to ensure that 
compilation does not 
extend across screen 
boundaries. 


Set up for DROP . Get 
the top return address 
from the return stack. 


Drop this address 
(which is the address 
of 7STACK ), following 
EXECUTE in 
INTERPRET . 


This is the entry point 
for the "faise portion" 
of the IF that checked 
to see if the block 
number was at the end 
of a screen. 


-^NULL3/ 


THEN 



;S (Run time portion of 

;.) Stop interpret¬ 
ing this definition 
and return to the 

r»g!linn n• t'O 
wQjuii vj<^o\juiO« 


IMMEDIATE 


Set the precedence 
bit of this 
definition so it 
will be executed at 
compile time and not 
compiled into the 
definition. 


Branch around the 
"false portion" of the 
IF that checked to see 
if interpreting from 
terminal. 


ELSE 


. (nulli^ 


R> 


DROP 


) - 

_I 

1 


Remove the top value 
of the return stack 
and place it onto 
the top of the 
parameter stack. 




Drop the top 
parameter stack 
entry. 


This is the entry point 
for the "false portion" 
of the IF that check if 
interpreting from 
terminal. 



This is identical to 
the previous R> DROP . 
Actually NULL would be 
more understandable if 
the R> DROP's were 
factored together. 


This is the entry point 
for the ELSE branch 
around the "false 
portion" of the IF that 
checked if the system 
was in interpretaion 
state. 
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NUMBER 

NUMBER ( address of text string — double precision value ) 

NUMBER uses the current base to convert a character string into a signed double precision number. The character string must begin 
with a length byte (e.g., standard "WORD" format). The position of the last decimal point encountered (if any are present) will be left in 
DPL . 

Error Message 0 ("?") is issued if a non-convertible character is encountered. 

The ascii character blank (20H) terminates the conversion process. 

Note that there are only two valid non-convertible characters: 

1. Decimal points, that are effectively ignored. 

2. A minus sign in the first character, that is used to set the sign bit to negative. 

A high level logic flowchart of NUMBER is provided as Figure NUMBER-1 so that the overall logic of the word can be more easily 
grasped. 

INTERPRET is an example of a word that uses NUMBER . 

* At entry - The top of the parameter stack contains a 16-bit address which points to the text string to be converted. The 
first byte of the text string contains the length of the following string. A decimal point may be present anywhere in the 
text. The first character of the text string may be a minus sign signifying a negative number. The user variable BASE 
contains the numeric conversion base. 

* At exit - The signed 32-bit double precision numeric conversion value is on the top of the parameter stack with the most 
significant word on the top of the stack and the least significant word as the second entry. The user variable DPL 
contains a number reflecting the number of digits occurring to the right of the last encountered decimal point. A value of 
-1 indicates no decimal point was encountered. 

LIKELY ERROR MESSAGES: 

? pronounced "HUH?" (0) -- The word in question is not a number. 

NUMBER is a high level colon definition. 

Refer to (NUMBER) , DPL , BASE , and WORD . 

FORTH-79: The FORTH-79 equivalent for NUMBER is CONVERT . 

Definition: : NUMBER ( address of text string — double value ) 

0 0 ROT DUP 1+ Cla) 2D = DUP >R 
+ -1 BEGIN 

DPL 1 (NUMBER) DUP Cfa) BL - 
WHILE 

DUP Cfal 2E - 0 7ERROR 0 
REPEAT 

DROP R> IF DMINUS THEN ; 
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BEGIN 


WHILE 


REPEAT 



High Level Logic of NUMBER 


DOCOL 


D 


D 


ROT 


DUP 


1 + 


qa 


The logic boxes in this flowchart correspond roughiy 
to the curly brackets in the low level flowchart. 


LIT 

2DH 
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DUP 


>R 


LIT 

-1 


BEGIN 



DPL 


(NUMBER) 


DUP 


C@ 



BL 


WHILE 


DUP 


cm 


LIT 
2 EH 



BRANCH past the 
REPEAT portion of this 
structure if flag was 0 
(i.e., a terminating 
space was encountered). 


At this point, the only 
legal non-convertible 
character is a decimal 
point so test for it. 
Execute TERROR if it 
was any other 
character. Else just 
loop back and continue. 



Duplicate the address 
of the unconvertible 
character. 


Pick up the character 
that could not be 
converted. 


Put a decimal point on 
the top of the stack so 
can check if the 
character is a decimal. 


Set up for TERROR . Is 
the character a decimal 
pointT 


Place the constant 
value 0 onto the top 
of the parameter 
stack. 


Set up to issue Error 
Message 0 ("T"). 
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?ERROR 

Issue the specified 
error message and 
QUIT if the truth 
flag is true. 




0 

Place the constant 
value 0 onto the top 
of the parameter 


REPEAT 


Issue an error message 
if the result of the 
subtraction was not 0. 
i.e., The character is 
not a decimal point. 
Note: If an error 
message is issued, a 
QUIT will also occur 
and execution will stop 
here. 


Set up to store a 0 
into DPL . 





Branch. 

1 - 

1 


»(numbi) 


BRANCH back to do 
"BEGIN portion" of this 
structure and continue 
conversion. 


THEN 

.(numbT)-^ 


;S (Run time portion of 

; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


(NUMB2^- 


DROP 


R> 



This is the entry point 
from the WHILE portion 
of the structure (i.e., 
exit from the 
conversion loop). 

Note: The converted 
number will now occupy 
the top two parameter 
locations as a signed 
32-bit double precision 
number. 


Drop the address of the 

non-convertible 

character. 


Retrive the is-it-a 
negative-number? truth 
flag. 


Is the number a 
J negative number? If so, 
execute DMINUS to * 
make it negative. 



"true portion" of the IF 
statement. 


DMINUS 


Convert the 32-bit 
double precision 
value on the top of 
the stack to its 
two's complement 
(i.e., make it 
negative). 


A minus sign preceded 
the character string to 
convert, so make the 
number negative. 


This is the entry point 
from the false branch 
of the previous IF 
statement which tested 
to see if the number 
was negative. 
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OFFSET 

OFFSET ( — data address ) 

OFFSET is a user variable that contains a block "offset" to mass-storage devices. Upon entry BLOCK adds the contents of OFFSET to 
the desired block number. This allows explicit selection of a specific device, i.e., The beginning block number of that device is stored 
into OFFSET. Future block references are then "offset" by that value and automatically reference the selected device. 

DRO and DR1 ("Drive 0" and "Drive 1") are device selection words that store beginning block numbers into OFFSET . 

MESSAGE adjusts the block number of the message line so that the message is always relative to physical Drive 0 irreqardless to the 
contents of OFFSET . 

OFFSET is thoroughly covered in the description of BLOCK . 

The user variable OFFSET is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable OFFSET . 

Refer to BLOCK , DRO , DR1 , MESSAGE , and USER . 

EORTH-79: The FORTH-79 equivalent for OFFSET is OFFSET . 
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OR 


OR ( vakiel \ value2 — logical result) 

OR (pronounced "or") performs a bit-wise logical OR function on the top two values on the parameter stack and replaces them with their 
logical result. 

UPDATE is an example of a word which uses OR . 

* At entry - The first and second parameter stack entries both contain an absolute 16-bit single precision value to be ORed. 

* At exit - The top of the parameter stack contains the absolute 16-bit single precision logical result. 

OR is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for OR is OR . 



HPUSH Push result onto top of 


stack. 

NEXT 
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OUT 

OUT ( — data address ) 

OUT is a user variable which contains a value incremented by EMIT . VLIST is the only system word that alters and references OUT . 
Applications may utilize OUT for purposes of formatting lines of text but note that EMIT only increments the value. No initialization or 
checking of OUT is performed by the sytem. 

The user variable OUT is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable OUT . 

Refer to EMIT , VLIST , and USER . 

FORTH-79: There is no FORTH-79 equivalent for OUT . 
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OVER 


OVER ( vahje2 \ valuel — vahie2 \ valuel \ vahje2 ) 

OVER copies the second parameter stack entry onto the top of the parameter stack. 
BEFORE AFTER 


OVER is a very commonly used word. The definition WORD is an example of a word that uses OVER . 

* At entry - The second parameter stack entry contains the 16-bit value to be copied onto the top of the stack. 

* At exit - The value at the top of the parameter stack equals the value now at the third stack entry. 

OVER is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for OVER is OVER . 


Top of parameter stack —> 


valuel 


value2 

value2 


valuel 



value2 



DPUSH Push "old" top of stack 


value. 

HPUSH Push what was the 

second entry onto the 
top of the stack. 

NEXT 
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PAD 


PAD ( — address ) 

PAD (named for scratch PAD) places the address of the text output buffer onto the top of the parameter stack. PAD does not occupy a 
fixed location in memory; instead it is always a fixed offset away from the current end of the dictionary. 

The PAD buffer is not a fixed length. It occupies memory between the end of the dictionary and the beginning of the user area. How 
much buffer is available at any time is a factor of both the installation memory map and the current dictionary size. 

PAD is referenced two ways: 

1. The pictured-numeric output words create numeric output text starting one byte before PAD and working towards low 
memory. (Refer to<# , ft , ftS , and #> .) 

2. Application words such as text-editor words use PAD as a text buffer; with the beginning character stored in the first byte and 
the rest of the characters going towards high memory. 


Dictionary 


Low Memory 

<- 


Numeric 

Conversion 


P 

A 

D 


Text 

Output 


High Memory 

~> 


User 

Area 


* At entry - No parameters. 

* At exit - The top of the parameter stack contains the 16-bit beginning address of the PAD area. 


PAD is a high level colon definition. 


FORTH-79: The FORTH-79 equivalent for PAD is PAD . 

Definition: : PAD ( - address) 

HERE 44 + ; 


DOCOL 


HERE 


LIT 

44H 


+ 


;S 



Set up for + . i.e., 
Get end address +1. 


Set up for + . 8080 
fig-FORTH uses offset 
of 68 (decimal) bytes 
past the end of the 
dictionary. 


Calculate absolute 
address of PAD . 
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PFA 


PFA ( Name Reid Address — Parameter Reid Address ) 

PFA (pronounced "P-F-A") converts a given Name Field Address (NFA) of a dictionary definition into its Parameter Field Address 
( PFA). 


me suuuLuic ui 


of 3 FORTH definition is; 


Name Field 
Link Field 
Code Field 
Parameter Field 


Variable length 
2 byte address pointer 
2 byte address pointer 
Variable length 


An example of the use of PFA can be found in the word (;CODE) . 

* At entry - The top of the parameter stack contains the 16-bit Name Field Address of a FORTH definition. 

* At exit - The top of the parameter stack contains the 16-bit Parameter Field Address of the specified FORTH definition. 

NOTE: Since the fig-FORTH Name Field is a variable length, a simple subtraction cannot be used to directly calculate the Parameter 
Field Address. TRAVERSE must be used instead. 

The exact nature of PFA may vary from system to system due to differing word sizes. 


PFA is a high level colon definition. 


Refer to NFA , CFA , and LFA . 

FORTH-79: There is no FORTH-79 eq uivalent for PFA . A FORTH-79 program may not address into a definition's Parameter Field. 

Definition: : PFA ( NFA -- PFA ) 

1 TRAVERSE 5 + ; 


DOCOL 


1 


TRAVERSE 


LIT 

05H 


+ 


;S 



8080 fig-FORTH 
Version 1=1 


Set direction indicator 
for TRAVERSE. This 
will cause a search 
direction from low to 
high memory. 


This will result in the 
address of the last 
byte of the Name Field 
being left on the top 
of the parameter stack. 

Set up for addition. 


Skip over the Link and 
Code Fields (i.e., aim 
at the beginning of the 
Parameter Field). 
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PREV 


PREV ( — data address ) 

PREV (pronounced "PREV" ) is a system variable that contains the address of the most recently (PREViously) referenced disk buffer in 
the buffer-array. PREV is used by buffer-referencing management routines. The use of PREV is explained in detail in BLOCK . 

Note that PREV is a system variable and not a user variable. 

PREV is normally initialized to point to FIRST (the "first" buffer). In the fig-Model, this is done by using the "initial value" feature of 
the word VARIABLE (e.g., BUF1 VARIABLE PREV ). This is not good programming practice and in the 8080 fig-FORTH Version 1.1 
PREV is initialized by COLD . 

The system variable PREV is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending ipon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the system variable PREV . 

Refer to BLOCK , BUFFER , +BUF , COLD , and VARIABLE . 

FORTH-79: There is no FORTH-79 eguivalent for PREV . 
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QUERY 


QUERY ( - ) 

QUERY inputs up to 80 (decimal) characters of terminal text. Text input is prematurely halted by encountering a carriage return. 

Text is placed into the Terminal Input Buffer, as specified by the contents of the user variable TIB . After text is input, the character 
pointer IN is set to Q. The carriage return is not stored in memory. A null (0) and a blank (20H) is appended to the end of the character 
string. 

An example of the use of QUERY is in QUIT where QUERY is used to read in a line of text for INTERPRET . 

* At entry - No parameters. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

EXECIJTION ONLY (12H) — This word must not be used while the system is in compile mode. 

QUERY is a high level colon definition. 

Refer to EXPECT , WORD , and TIB . 

FORTH-79: The FORTH-79 equivalent for QUERY is QUERY . 

Definition: : QUERY ( --) 

TIB fa) 50 EXPECT 0 IN 1 














QUIT 

QUIT (- ) 

QUIT stops compilation, resets the return stack pointer, and starts interpretation from the input terminal data stream. The name "QUIT" 
is a rather ambiguous description of the function this procedure performs. Actually QUIT is used to initially start up FORTH, to "quit" 
execution of a routine, and to be the most basic and primary loop of the FORTH system. QUIT is an endless loop which calls the 
Interpreter repeatedly. 

wuii is an enoiess loop that inputs a line of text from the terminal and then calls the interpreter to process that text. After QUIT 
initially calls the Interpreter, commands from the terminal (residing in the Terminal Input Buffer) are executed which can cause any level 
of nesting. The eventual un-nesting of these levels always returns to QUIT . It is also possible to exit from any level of nesting by 
issuing QUIT (hence fc h e narne QUIT). This resets the return stack (i.e., absolutely erases any levels of nesting), sets input to come from 
the terminal, and starts INTERPRET . r 

When control returns from INTERPRET (see NULL ), QUIT issues the prompt "OK" to the terminal. 

* At entry - No parameters. 

* At exit - No parameters. 

QUIT is a high level colon definition. 

Refer to INTERPRET , and NULL . 


FjORTH-79: The FORTH-79 equivalent for QUIT is QUIT , although the FORTH-79 version does not output any message. 
Definition: 

[COMPILE] [ 


DOCOL 


BLK 


[COMPILE ] 


QUIT ( - ) 

0 BLK 1 
BEGIN 

RP1 CR QUERY INTERPRET STATE (3 0= 
IF ." OK" THEN 
AGAIN : 


(quit) 


(Run time portion of 
:) Save IP and 
start interpreting 
this definition. 


Suspend compilation. 
Set the user 
variable STATE to 0. 


I Set the system 
< interpret input 
the terminal 


im to 1 
iut from S. 


Place the 
value 0 on 
of the par 
stack. 

constant 
to the top 
ameter 



Place the address of 
the user variable 

BLK onto the top of 
the parameter stack. 



Store the specified 
value into the 
specified memory 
location. 



Force com 
the follow) 
IMMEDIA1 

-1 

pilation of 
ng 

'E word. 


Set up for 1 
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Set up for I . BLK 
contains the block 
number currently being 
interpreted. 


Storing a zero into BLK 
causes the Interpreter 
to get input from the 
terminal. 


Since [ is an IMMEDI¬ 
ATE word, [COMPILE] 
must be used to 
compile it into 
the definition. 
(Otherwise it would 
execute instead of 
being compiled. 
[COMPILE] is only used 
at Sequence 1 time to 
"compile" [ into 
QUIT's definition when 
QUIT is executed at 
compile time (Sequence 
2 ). 


BEGIN 


.(quiti)- 


rp: 


CR 


Initialize the 
return stack 
pointer. 


QUERY 


Output an ascii 
carriage return 
(ODH) and linefeed 
(OAH). 


Input a line of text 
from the input 
terminal. 


[ is compiled at 
Sequence 2 into QUIT's 
definition. It is 
executed later at 
Sequence 3. The 
Sequence 3 action of [ 
is to set the stystem 
to interpret and 
execute input from the 
terminal. 

{ This is the interpret I 
loop of the FORTH > 
system. I 

This is the entry point 
to the "loop body" from 
the AGAIN portion of 
the BEGIN-AGAIN loop. 


The return stack is 
re-set each "trip" 
through the main 
interpret loop. 


Set up the terminal for 
the next input line. 


Read the typed in text 
from the terminal. 













INTERPRET 


STATE 


0 = 


IF 


_ 1 

Interpret 
execute or 
text from 

stream. 

ind 

compile 
the input 

Executing some 
commands can cause 
compilation to occur 

f n « r»on 

?s 

(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 



cause compilation to 
occur off of disk (e.a.. 



LOAD ). No matter how 
deep nesting occurs, 
non-ABORPed proces¬ 
sing eventually returns 
here again when the last 
of the original text input 
is finished being 
interpreted. _ 

I Print "OK" if not 

| compiling. 


Place the address of 
the user variable 
STATE onto the top 
of the parameter 
stack. 


Replace the address 
on the top of the 
parameter stack with 
the memory contents 
of that address. 


Replace the value on 
the top of the 
parameter stack with 
a true boolean flag 
(1) if the value is 
equal to uj else, 
replace it with a 
false flag (0). 


t 

* 


Set up for (a) . If ST ATE 
contains a 0, the 
system is interpreting 
and executing the input 
stream. A non-zero 
value denotes 
compilation. 


Pick up the contents of 
STATE . 


Set up for IF . Want to 
execute "true portion" 
of IF if STATE equals 
0 (i.e., if 
interpreting). 



^ (QUIT2) 

Branch if the system is 
in compilation state 
and not interpreting 
from the input 
terminal. 


." OK" 

THEN 
. (QLnT2> 


AGAIN 


Print the ascii 
characters "OK" onto 
the output device. 


Branch. 


This is where the 
friendly FORTH "OK" 
comes froml 


Entry point for the 
"false portion" of the 
previous IF . 

Control branches around 
the ." OK" if the 
system is compiling and 
not interpreting. 




Loop back to the BEGIN 
portion of this 
BEGDM-AGAIN loop and 
interpret the next line 
of text. This is an 
infinite looo. 


Note that this ;S is 
never executed. 
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R 


R ( — value on top of return stack ) 

R copies the top of the return stack to the top of the parameter stack. In this sense, it performs the same function as I (although, due to 
installation differences, I should still be used with "do-loops" to perform this function). 

Note that R does not "drop" the top of the return stack and therefore cannot be used to compensate for the use of >R . 

(.") is an example of a word which uses R. 

* At entry - No parameter stack entries but the top of the return stack contains the 16-bit value to be copied. 

* At exit - The top of the parameter stack contains the copied 16-bit value. 

R is a low level code primitive. 

Refer to I. 

FORTH-79: The FORTH-79 equivalent for R is R|a) . 


Definition: 


R/W ( buffer address block number R/W flag -- ) 
USE >R SWAP SEC/BLK * ROT USE 1 
SEC/BLK 0 DO 

OVER OVER T&SCAL IF 

ELSE 


1+ 80 USE +1 

LOOP 

DROP DROF 3 R> USE ! ; 


THEN 


( 8080 Version 1.1 ) 


SECRD 

SECWR 



NEXT 
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R# 


R# ( — data address ) 

R# (pronounced "R-sharp") is a user variable that may be used by file related functions such as editing. R# is not used in the basic 
FORTH system. 

_ ..»*-*«• ._ i i / L : t 1 ~ wnluo \A/Kon in momnrv. t-hp hinh and lnw order bvtes mav be switched 

ine user variaDie is si-oreu as a id-uh sinyic H lot -‘°‘ u " ,d,u,j . . .. > 1 — - __ 

depending upon the processor used. 

* At entry - No parameters. 

* /\t exit - The top of the parameter stack contains the 16-bit address of the user variable R# . 


Refer to USER . 

FORTH-79: There is no FORTH-79 equivalent for R# . 
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R/W 


R/W ( buffer address \ desired block number \ R/W flag — ) 

R/W (pronounced "R-slash-W") is the standard fig-FORTH mass-storage interface word. All mass storage data transfers are performed 
by this word. In general, I/O words below BLOCK are system dependent. The following description is for the 8080 fig-FORTH Version 
1.1 under a CP/M environment. This is, however, a very good example of an implementation of R/W . 

The word has two major functions: 

1. To convert the specified virtual block number into an absolute addrsss on a physical davics 

2. To perform the actual data transfer between the device and memory. 


The conversion of a block number (which to the programmer represents data residing in memory) into a physical device address is the 
heart of the virtual aspect of FORTH I/O. Any type, or combinations of types of mass storage devices may be used; although for 
practical purposes each device must be randomly accessible. The most common mass storage devices are floppy disk, hard disk, and 
magnetic tape. 


Device selection is based solely upon block number range. Each storage device in the system has an unique range of block numbers 
assigned to it. This allows each block in the system to be unique. For example, Disk Drive 1 may contain blocks 0 throuqh 799; while 
Disk Drive 2 may contain blocks 800 through 1199; and Tape Drive 3 may contain blocks 1200 through 1399. 


The word BLOCK provides a mechanism where drives may be implicitly referenced by biasing the desired block number with the startinq 
block number of the selected device. (See BLOCK , OFFSET , DR0 , and DR1 .) Note that by the time R/W is called, this block number 
must have been converted to an absolute block number. 


The conversion by R/W of this absolute block number into a physical hardware address is obviously completely dependent on the 
characteristics of the selected device. 


Likewise, the actual I/O driver routines will vary from system to system. R/W may contain any number of I/O drivers for whatever 
devices are connected to the system. 

Note that, since the I/O drivers are installation dependent, any I/O error checking routines are also installation dependent. FORTH does 
not have to perform unverified I/O. Any desired degree of error checking or retries may be put into R/W . 

* At entry - The top of the parameter stack contains a Read or Write boolean flag. A zero flag indicates that a write is to 
occur; a non-zero flag, that a read is to occur. The second stack entry contains an absolute 16-bit absolute block 
number. This value may range from 0 to 32,767. The third stack entry contains the 16-bit buffer address of the beqinninq 
of the data to be transferred. 

* At exit - No parameters. 

R/W is a high level colon definition. 


Refer to BLOCK , +BUF , BUFFER , OFFSET , DR0 , and DR1 . 

FORTH-79: There is no FORTH-79 equivalent for R/W . 

Definition: : R/W ( buffer address block number R/W flag — ) 

USE >R SWAP SEC/BLK * ROT USE l 
SEC/BLK 0 DO 

OVER OVER T&SCAL IF 

ELSE 

THEN 


( 8080 Version 1.1 ) 

SECRD 

SECWR 


1 + 
LOOP 
R> USE : 


80 USE +1 

LOOP 

DROP DROP 

This is an example of a R/W implementation for the 8080 fig-FORTH Version 1.1 in a CP/M environment. 


DOCOL 


USE 



(Run time portion of 
:) Save IP and 
start interpreting 
this definition. 


Place the address of 
the system variable 
USE onto the top of 
the parameter stack. 


8080 fig-FORTH 
Version 1.1 


USE contains the 
address of the next 
buffer to be allocated. 


fa) 


Replace the address 
on the top of the 
parameter stack with 
the memory contents 
of that address. 


Fetch the contents 
of USE . 


In this particular 
installation, the CP/M 
I/O routines use the 
address contained in 
USE as an I/O buffer 
address. 
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>R 


SWAP 


SEC/BLK 


ROT 


USE 


SEC/BLK 


(DO) 



OVER 


T&SCAL 


IF 


Copy the second 
parameter stack 
value onto the top 
of the parameter 
stack. 


Copy the second 
parameter stack 
value onto the top 
of the parameter 
stack. 


Installation 
dependent word to 
convert the absolute 
sector displacement 
on the top of the 
parameter stack into 
a specific drive, 
track, and sector 
number. 


These two OVER's 
perform the same action 
as a 2DUP . 


The absolute sector 
displacement and the 
read/write flag are 
duplicated so they may 
be reused as often as 
necessary. 


This is an extremely 
important function of 
R/W . It converts the 
virtual block number 
into a physical 
hardware address. 
Obviously, the word is 
completely installation 
dependent. 



>( RSLW2 ) 

Branch if the R/W flag 
specified write. 


SECRD Installation 

] dependent word to 
read a physical 
sector. 


Branch. 


Read one sector (not 
necessarily a whole 
block) into the buffer. 


=*(RSLW3) 



Temporarily save the 
original contents of 
USE on the return 
stack. This will be 
restored when R/W is 
finished. 


Place the desired block 
number onto the top of 
the parameter stack. 


Set up for * . 


Calculate the absolute 
sector displacement of 
the desired data by 
multiplying the desired 
block number by how 
many sectors there are 
per block. 

Bring the data address 
to the top of the 
stack. 


Set up for 1. USE 
contains the CP/M I/O 
buffer address. 


Store data address into 
USE . 


Set up Limit value for 

r\0 /! « On f Krpi inh 

the loop, reading or 
writing one sector at a 
time, until a complete 
block of data has been 
transferred). 


Set up Initial value 
for DO . 


This execution time 
portion of DO is 
compiled into this 
definition by DO (at 
R/W's Sequence 2). 


This is the entry point 
for the jump from the 
LOOP portion of this 
DO-LOOP structure. 


ELSE 

! (RSLW2) 


THEN 

!(rSLW3)-^ 


Branch around "false 
portion" of the IE 
structure. 


This is the entry point 
for the "false portion" 
of the previous IE 
(i.e., the R/W flag was 
0 so write instead of 
read). 

Write one sector (not 
necessarily a whole 
block) into the buffer. 


This is the entry point 
from the "true portion" 
of the F structure 
(i.e., Did a read, do 
not "fall through" and 
do a write too). 

Increment the absolute 
sector displacement to 
aim at the next sector 
(i.e., transfer the 
next sector of the 
block.) 


1 + 


Increment the top 
parameter stack 
value by 1._ 


SECWT 


Installation 
dependent word to 
write a physical 
sector. 
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LIT 

80H 


USE 




(LOOP) 


LOOP 


DROP 


DROP 


R> 


USE 


;s 



258 











RO 


RO ( — data address ) 

RO (pronounced "R-zero") is a user variable which contains the initial address of the return stack 
RO is initialized by COLD during system start up with data from the origin parameter area. 


QUIT uses the address in RO to reset the return stack. 

The user variable RO is stored as a 16-bit single precision value, 
depending upon the processor used. 


When in memory, the high and low order bytes may be switched 


* At entry - No parameters. 

• At exit - The top of the parameter stack contains the 16-bit address of the user variable RO 


Refer to QUIT , COLD , and USER . 

FORTH-79: There is no FORTH-79 equivalent for RO . 


259 



R> 


R> ( — value popped from return stack ) 


R> (pronounced "R-from") pops a number off of the return stack and places it onto the top of the parameter stack. It is often used in 
conjunction with >R in order to restore the return stack to its original state. 


NJDTF* Tho 5 rvo ClT»T»ar«f lino D \ nnn - ——I _ I : 4 _ 1 » > • . Ill . . ■ . . 

■ ,w • — # uou u 1 ^ ai 1 inaetcrmuiauj results, tviosc liKeiy tne system would crash. 

R> outside of a colon definition will probably cause a system crash. 


Although not "illegal," the use of 


R> differs from R in that the value is removed, or "popped", from the top of the return stack rather than copied. 

REPEAT is an example of a word which uses R>. 

* At entry - No parameter stack entries. The top of the return stack contains the 16-bit value to be transferred. 

* At exit - The top of the parameter stack contains the 16-bit value which was previously on the top of the return stack. 
R> is a low level code primitive. 

Refer to >R , and R . 

FORTH-79: The FORTH-79 equivalent for R> is R> . 



NEXT 
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REPEAT 


REPEAT 

COMPILE TIME (Sequence 2): ( loop address \ 1 \ offset location \ 4 — ) 

EXECUTION TIME (Sequence 3): ( - ) 

REPEAT is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution 
time. 

REPEAT is used to mark the end of a BEGIN-WHILE-REPEAT structure in the form: 

BEGIN 

"Set Exit Conditional" 

WHILE 

"True Portion of Loop Body" 

REPEAT 

Refer to WHILE for a description of the action of a BEGIN-WHILE-REPEAT loop. 

At compile time (Sequence 2), REPEAT primarily does two things: 

1. REPEAT compiles the unconditional branch back to BEGIN (i.e., the loop action of the structure). 

2. REPEAT resolves and stores the exit branch offset located in WHILE. Upon exit, WHILE uses this branch to exit to the word 
immediately following REPEAT . 

The unconditional branch is compiled by executing an AGAIN , which inputs the loop address and the value 1 left by the BEGIN . The 
processing necessary to resolve the exit offset in WHILE is identical to that of resolving the OBRANCH in an IF ; therefore, an ENDIF is 
used. ENDIF expects the value 2 on the stack for compiler security. REPEAT subtracts 2 from the value on the stack and since WHILE 
left the value 4, it is likely that an unmatched WHILE and REPEAT will be detected. 

The run time action (Sequence 3) of REPEAT is to cause an unconditional BRANCH back to the first word after BEGIN . Then whatever 
processing necessary to set the exit boolean flag can be performed and the loop repeated. 

BEGIN-WHILE-REPEAT loop structures must be used within a colon definition. 

Note that REPEAT is an IMMEDIATE word. This means that its precedence bit is set and it wiii therefore execute at compile time. 
NUMBER is an example of a word which uses REPEAT. 


COMPILE TIME (Sequence Zh 

* At entry - The top of the parameter stack contains the 16-bit signed single precision value 4. This value is left on the 
stack by WHILE and is tested by REPEAT for compiler security to ensure that the BEGIN-WHILE-REPEAT structure does 
contain a WHILE . The second stack entry contains the 16-bit address of the reserved OBRANCH offset location created 
by the IF inside of WHILE . The third stack entry contains the 16-bit signed single precision value 1 left by the BEGIN to 
ensure that the structure is started with a BEGIN . The fourth stack entry contains the 16-bit address of the first location 
following the BEGIN statement (i.e., the loop address). 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - No parameters. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

COMPILATION ONLY (11H) — This word may only be used within a colon definition. 

CONDITIONALS NOT PARED (13H) - There is some sort of problem with the pairing of conditionals within the definition being 

compiled. 

REPEAT is a high level colon definition. 

Refer to BEGIN , WHILE , AGAIN , ENDIF and BRANCH . 

FORTH-79: The FORTH-79 equivalent for REPEAT is REPEAT . 

Definition: : REPEAT ( loop address\ 1 \ offset location\ 4--) 

>R >R [COMPILE] AGAIN R> R> 2 - [COMPILE] ENDIF ; IMMEDIATE 
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COMPILE TIME action of REPEAT Sequence 2): ( loop address \ 1 \ offset location \ 4 — ) 


DOCOL 


>R 


>R 


[COMPILE] 


AGAIN 


R> 


R> 


2 
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Save the value 4 on the 
return stack for 
ENDIF . 


Save WHILE's exit 
branch offset location 
for ENDIF . 


Since AGAIN is an 
IMMEDIATE word, 
[COMPILE] must be 
used to compile it into 
the definition. 
(Otherwise it would 
execute instead of being 
compiled.) [COMPILE] 
is only used at 
Sequence 1 time to 
"compile" AGAIN 
into REPEAT and does 
not exist in REPEAT's 
definition when REPEAT 
is executed at compile 
time (Sequence 2). 


AGAIN will be executed 
at a later compile 
time (Sequence 2) when 
REPEAT is executed. It 
will then use its input 
parameter, address and 
1 . 


Retrieve the previously 
saved exit offset 
location. 


Retrieve the previously 
saved compiler security 
value 4. 


Set up for - . 


[COMPILE] 


ENDF 


;S 


IMMEDIATE 



Subtract 2 from the top 
value on the stack. If 
there is a corresponding 
WHILE the result 
will be 2. 


Since ENDIF is an 
IMMEDIATE word, 
[COMPILE ] must be 
used to compile it into 
REPEAT's definition. 
(Otherwise it would 
execute instead of 
being compiled.) 
[COMPILE] is only use 
at Sequence 1 time to 
"compile" ENDIF into 
REPEAT and does not 
exist in REPEAT's 
definition when REPEAT 
is executed at compile 
time (Sequence 2). 


Set the OBRANCH 
offset in the preceding 
WHILE to branch to and 
execute the "false 
portion" of the 
structure (i.e., store 
an offset which points 
to the next definition 
following the 
BEGIN-WHILE-REPEAT 
structure). 


REPEAT is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 













EXECUTION TIME action of REPEAT (Sequence 3): ( — ) 

Repeat is the "loop back" portion of a BEGIN-WHILE-REPEAT loop. 



EXIT 









ROT 

ROT ( valuel \ vahie2\ value 3 — value2 \ value3 \ valuel ) 

ROT (pronounced "rote") rotates the top three 16-bit values on the parameter stack. The third value is placed onto the top of the stack 


BEFORE AFTER 

- . ^ .. v valuel 

l op OT parameter btaCK-/ v ■ - - 

value2 value3 

valuel value2 


NUMBER is an example of a word that uses ROT . 

* At entry - The parameter stack contains three 16-bit values to be rotated. 

* At exit -The 16-bit value which was previously the third stack entry is not on the top of the stack. The first and second 
stack entries are each one deeper in the stack. 

ROT is a high level colon definition. 

FORTH-79: The FORTH-79 equivalent for ROT is ROT . 

Definition: : ROT ( valuel\ value2\ value3 — value2\ value3\ valuel ) 

>R SWAP >R SWAP ; 


DOCOL 


>R 


SWAP 


R> 


SWAP 


;s 



Temporarily get the 
first entry out of the 
way. 


"Bubble" the "third" 
entry up into the 
"second" entry. 

Retrieve the first 
entry. 


"Bubble" the "third" 
entry up onto the top 
of the stack. 
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RP! 


RP! ( - ) 

RP1 (pronounced "R-P-store") is an installation dependent word that initializes the return stack pointer to the address contained in the 
user variable RO. This is the commonly used method of initializing the return stack pointer. 

RP! is used in COLD and QUIT . 

* At entry - No parameters. 

* At exit - No parameters. 

RP! is a low level code primitive. 

Refer to RO . 

FORTH-79: There is no FORTH-79 equivalent for RP! . 



NEXT 
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RP@ 

RP@ ( — return stack pointer address ) 

RP(a) (pronounced "R-P-fetch") is an installation dependent word that returns the return stack pointer address, present at the time RPiaO 
was initially invoked, to the top of the parameter stack. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the 16-bit address of the top of the return stack. 

RP@ is a low level code primitive. 

FORTH-79: There is no FORTH-79 equivalent for RPfa! . 



HPUSH 


Put address on top of 
stack. 


NEXT 
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S->D 


S->D ( single precison number — double precision number ) 

S->D (pronounced "S-to-D") extends a signed single precision number to form a signed double precision number. 

WARNING! S->D must be used to convert single precion values to double precision values in order to correctly propagate the sign bits. 


/MOD is an example of a word that uses S->D . 

* At entry - The top of the parameter stack contains a signed 16-bit single precision value. 

* At exit - The top of the parameter stack contains a signed 32-bit double precision value with the high order word 
(containing the extended sign) on the top of the stack and the original value in the second stack entry. 


S->D is a low level code primitive. 


r ORTH-79; 


p |G PQDTLJ^Q aisn t f QP S_\P) 



DFJSH 

PUSH 16 =bit value back 
onto stack. 

HPUSH 

PUSH 16-bit extended 
sign onto stack. 

NEXT 
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so 

SO ( — data address ) 

SO (pronounced "S-zero") is a user variable that contains the initial address of the parameter stack. SO is initialized by COLD during 
system start up with data from the origin parameter area. 

ABORT uses the address in SO to reset the parameter stack. 

SPI fetches the contents of SO when it initializes the parameter stack. 

The user variable SO is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable SO . 

Refer to ABORT ,COLD , SPI and USER . 

FORTH-79: The FORTH-79 equivalent for SO is SO . 
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SCR 


SCR ( — data address ) 

SCR (pronounced "S-C-R") is a user variable that contains the screen number most recently referenced by LIST . This value can then be 
referenced by other words—especially editor commands—so that the desired screen number does not have to be explicitly stated every 
time a command is issued. 

The user variable SCR is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable SCR . 

Refer to LIST , and USER . 

PQRTH-79; The FORTH-79 equivalent for SCR is SCR = 
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SIGN 


SIGN ( sign flag \double precisian value — double precision value ) 

SIGN is normally used within a pictured numeric output expression to place a sign immediately to the left of a converted numeric 
character string. 

SIGN will place an ascii minus sign in the next available character string location if the sign of the third parameter stack entry (i.e., a 
sign nag , is negative, .he magnitude of the sign fiag entry is ignored. The top two entries contain a double precision value. 

The sign flag parameter is normally set up before the <# //S SIGN //> expression is executed. Generally the sign flag is the same sign as 
the double precision value to be converted. To set up for <// //S SIGN //> , the words SWAP OVER DABS will leave a copy of the hiqh 
order signed portion of the value in the third stack entry. This is what is done in D.R which uses SIGN for signed pictured numeric 
output. The description of <// and // explains more about pictured numeric conversion. 

* At entry - The third entry of the parameter stack must contain a signed 16-bit value which acts as a sign flaq. The top 
two entries contain a 32-bit double precision value. 

* At exit - The original third entry, the sign flag, in the parameter stack is dropped. The first and second stack entries 
remain untouched. 


SIGN is a high level colon definition. 

Refer to # , <// , //> , //S , HOLD , HLD , PAD , and DABS . 
FORTH-79: The FORTH-79 equivalent for SIGN is SIGN . 


Definition: 


GN 


ROT IK 


( flag\ double precision value — double precision value ) 


DOCOL 


ROT 


0 < 


F 


LIT 

2DH 


HOLD 



This is the entry point 
for the THEN portion of 
the previous IF . 


I The value was not j 
< negative so a minus I 
jjsign was not in memory.! 
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SMUDGE 


SMUDGE ( -) 

SMUDGE is used during word definition to toggle the "smudge" bit (binary mask value 20H) in the length byte of the Name Field of a 
definition so that the word cannot be "found" (via the word (FIND)) until the word is correctly compiled. The length byte is smudged at 
the beginning of compilation and is again smudged (toggled back) upon successful completion (usually by ;). 

* At entry - No parameters. 

* At exit - No parameters. 

SMUDGE is a high level colon definition. 


Refer to ; . 

FORTH-79: There is no FORTH-79 equivalent for SMUDGE . 


Definition: : SMUDGE ( --) 

LATEST 20 TOGGLE 


DOCOL 


LATEST 


LIT 

20H 


TOGGLE 


}S 



Set up for TOGGLE . 
i.e., Aim at the length 
byte of the definition 
being compiled. 


Set up for TOGGLE . 
Put the smudge mask 
(20H) onto the stack. 


XOR i.e., Toggle the 
smudge bit on or off 
depending on its 
present state. 


(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 
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SP! 


SP! (-) 

SPL (pronounced "S-P-store") is an installation dependent word that initializes the parameter stack pointer to the address contained in the 
user variable SO. This is the commonly used method of initializing the stack pointer. 

ABORT and ERROR are examples of words that use SP! . 

* At entry - No parameters. 

* At exit - No parameters. 

SP! is a low level code primitive. 

Refer to SO , ABORT , and ERROR . 

FORTH-79: There is no FORTH-79 equivalent for SP! . 



NEXT 
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SP@ 


SPfa) ( — parameter stack pointer address ) 

SPfa) (pronounced "S-P-fetch") is an installation dependent word that returns the parameter stack pointer address, present at the time 
SPfi was initially invoked, to the top of the stack. 

1CSP is a word that uses SPfa) . 

* At entry - No parameters. 

* At exit - The top of the stack contains the 16-bit stack pointer address. 

SPfa) is a low level code primitive. 

FORTH-79: SPfa) is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". 

8080 fig-FORTH 
Version 1.1 


HPUSH Put address onto top of 

stack. 

NEXT 
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SPACE 

SPACE ( - ) 

SPACE transmits an ascii blank (20H) to the output device. 

D. is an example of a word that uses SPACE . 

* At entry - No parameters. 

* At exit -No parameters. 

SPACE is a high level colon definition. 

FORTH-79: The FORTH-79 equivalent for SPACE is SPACE . 

Definition: : SPACE ( --) 

BL EMIT ; 


DOCOL 


BL 


EMIT 


?S 
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SPACES 


SPACES ( count — ) 

SPACES outputs a specified number of ascii blanks (20H) to the output device. 

D.R is an example of a word that uses SPACES . 

* At entry - The top of the parameter stack contains a signed 16-bit single precision value indicating the number of blanks 
to output. 

NOTE: Negative values are changed to zero. 

* At exit - No parameters. 

SPACES is a high level colon definition. 

FORTH-79: The FORTH-79 equivalent for SPACES is SPACES . 


Definition: 


DOCOL 


MAX 


-DUP 


IF 


(DO) 


SPACES ( count 
0 MAX -DUP 


IF 


0 


DO 


SPACE LOOP 


THEN 
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STATE 

ST ATE ( — data address ) 

STATE is a user variable which contains a value that reflects the compilation "state" of the system. 

A 0 value indicates that the system is compiling. A non-zero value (COH for the 8080 fig-FORTH Version 1.1) indicates that the system 
is interpreting. 

INTERPRET refers to the value in STATE to determine how to process the input data stream. 

[ sets STATE to interpret mode. 

] sets STATE to compile mode. 

During system start up, STATE is originally initialized by QUIT . 

The user variable STATE is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable STATE . 

Refer to [, ] , INTERPRET , QUIT , and USER . 

FORTH-79: The FORTH-79 eguivalent for STATE is STATE . 
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SWAP 


SWAP ( vakie2 \vahiel — valuel \ vahie2 ) 

SWAP exchanges the top two 16 bit values on the parameter stack. 

Before 

Top of Parameter Stack —> valuel 

value2 

SWAP is a very commonly used word. ROT is an example of a word that uses SWAP . 

* At entry - The top of the parameter stack and the second entry contain the 16-bit values to be exchanged. 

* At exit -The top of the stack contains the value previously in the second entry. The second entry will contain the value 
previously on the top of the stack. 

SWAP is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for SWAP is SWAP . 


After 

value2 

valuel 



rTPUSH Push what was the 


second entry onto the 
top of the stack. 


NEXT 
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TASK 


TASK ( - ) 

TASK is a no-op (no operation) definition that is used as a "boundary marker" between applications or program segments, 
simply consists of a colon, a name, and a semicolon. For example: 

: TASK ; 

TASK is normally compiled as the first word of an application, with all other application words following it in the dictionary. 
FORGET TASK will then forget all of the application up to (and including) the boundary defined by TASK . 

* At entry - No parameters. 

* At exit - No parameters. 

TASK is a high level colon definition. 

Refer to FORGET . 

FORTH-79: There is no FORTH-79 equivalent for TASK . 


The word 


A future 
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THEN 


THEN 

COMPILE TIME (Sequence 1): ( offset address\ 2 — ) 

EXECUTION TIME (Sequence 3): ( - ) 

THEN is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution 
time. 

THEN is used to make the end of an IF-THEN or IF-ELSE-THEN structure. ( END IF may be used in place of THEN but THEN is the 
preferred word.) THEN must be used in the form: 

IF "true portion" THEN 
IF "true portion" ELSE "false portion" THEN 
An IF-THEN structure must be used within a colon definition. 


THEN is actually a Sequence 1 compiling word. That is THEN compiles (during Sequence 1) another compiling word, ENDIF , into its 
definition. Then, at Sequence 2, when THEN is executed the word ENDIF does the actual compiling into the definition being created. 

The apparent Sequence 2 compile time action of THEN is to compute a forward branch offset, calculated from the supplied input 
parameter address to the next available memory location following THEN (supplied by HERE ) and to store that offset in the location 
reserved by the previous IF or ELSE statement. (Actually this is performed at Sequence 2 via the ENDIF which was compiled by THEN at 
Sequence 1.) 

Some compiler security is provided by checking for a 2 on the top of the stack. A THEN without a corresponding IF or ELSE will 
probably not encounter a 2 on the top of the stack during compilation. (NOTE: During compilation, IF and ELSE leave a 2 on the top of 
the stack.) 

The execution time action (Sequence 3) of THEN is to simply serve as the destination of a forward branch from a previous IF or ELSE 
statement. THEN compiles no run time code. 

Note that THEN is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 


COMPILE TIME (Sequence 2): 

* At entry - The top of the parameter stack contains the 16-bit signed single precision value 2 used for compiler security. 
The second stack entry contains a 16-bit address specifying both the branch offset address of a previous IF or ELSE and 
also the memory location that offset is to be stored into. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - No parameters. 


* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

COMPILATION ONLY (11H) -- This word may only be used within a colon definition. 

CONDITIONALS NOT PAIRED (13H) -- There is some sort of problem with the pairing of conditionals within the definition being 
compiled. 

THEN is a high level colon definition. 

Refer to IF , ELSE , and ENDIF . 

FORTH-79: The FORTH-79 equivalent for THEN is THEN . 

Definition: : THEN ( offset address\ 2 -- ) ( compile time ) 

[COMPILE] ENDIF ; IMMEDIATE 
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COMPILE TIME action of THEN (Sequence 1): ( offset address\ 2 — ) 


DOCOL 


[COMPILE ] 


ENDF 


;s 


IMMEDIATE 



Since ENDIF is an 
IMMEDIATE word, 
[COMPILE] must be 
used to compile it into 
the definition. 
(Otherwise it would 
execute instead of being 
compiled.) [COMPILE] 
is only used to "compile" 
ENDIF into THEN (at 
Sequence 1) and does 
not exist in THEN's 
definition when THEN is 
executed at compile 
time (at Sequence 2). 


ENDIF will be executed 
at a later compile 
time (Sequence 2) when 
THEN is executed. 


THEN is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


EXECUTION TIME action of THEN (Sequence 3): ( - ) 


THEN simply serves as the destination of a forward branch from a previous IF or ELSE statement. 
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TIB 

TIB ( — data address ) 

TIB (pronounced "T-I-B" for Terminal Input Buffer) is a user variable that contains the address of the Terminal Input Buffer. 

The Terminal Input Buffer is an area of memory reserved as a buffer area for the data stream coming from the terminal. The buffer is 
normally located in memory between the return stack and the parameter stack. The return stack "grows downward" into the buffer. 

The length of the buffer is usually 82 (decimal) bytes long, 80 characters + 2 terminators. The length is determined by a literal value in 
QUERY. 

TIB is initialized by COLD during system start up with data from the origin parameter area. 

The user variable TIB is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable TIB . 

Refer to QUERY , and USER . 

FORTH-79: There is no FORTH-79 equivalent for TIB . 


281 



TOGGLE 


TOGGLE ( address \ bit mask — ) 

TOGGLE Exclusive-OR's the contents of the memory location pointed to by the second stack location with the value on the top of the 
stack. Note: This is opposite "normal" usage (i.e., the address is usually on the top of the stack and the data is in the second stack 
entry). 


.;fi^ Ki». 




This word is named TOGGLE because of the effect of the Fvelnsiv/e.nR. "Tnnniinn" o .. ..... 

( < - -- “ “ • u uu Ul lUCy Uliai iljco UlC : 

I oggung that same bit again changes the bit back to its original state. (Using the same bit mask both times, of course.) 


bid L0 Ul LI 1C UIL 


Note that the word operates on one byte in memory. 

Also note that word addressing machines may behave differently. 
SMUDGE is an example of a word that uses TOGGLE . 


* At entry - The top of the parameter stack contains a 16-bit value. The low order 8 bits of this value are an Exclusive-OR 
bit mask. THe high order 8 bits are ignored. The second stack entry contains the memory address of the location to be 
"toggled". 

* At exit - No parameters. The specified memory location contains the logical result of the Exclusive-OR. 

TOGGLE is a low level code primitive. 

FORTH-79: There is no FORTH-79 equivalent for TOGGLE . 



NEXT 
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TRAVERSE ( beginning address \ direction — ending address ) 


TRAVERSE 


TRAVERSE calculates the address of the opposite end of a fig-FORTH variable length Name Field. Given either the address of the 
length byte or the address of the last letter of a Name Field, TRAVERSE moves across ("traverses") that Name Field. Note this means 
TRAVERSE moves across a Name Field in either direction. See the "At entry" section. 


TRAVERSE makes use of the fact that the "terminator flag" for both ends of the Name Field is the most significant bit (the 80H bit). By 
moving across the Name Field looking for a byte whose value is greater than 7FH. 


ri __. | k. ir~ a _J ni_ A »««»»»« i»Jr\ i ^K * i TO A V/F R QF 

I fie WUruS i Nr aa «i IU r\ die cXai i ipico i w ui uo vviuui uou , , -w , * . 


* At entry - The top of the parameter stack contains a 16-bit direction indicator value. 

If this direction indicator is a 1, motion is toward high memory and the second stack entry must be the address of the 
Name Field's length byte. 

If the direction indicator is a -1, motion is toward low memory and the second stack entry must be the address of the last 
letter of the Name Field. 

» At exit - The top of the parameter stack contains the address of the opposite end of the Name Field. The direction 
indicator is dropped. 


TRAVERSE is a high level colon definition. 


FORTH-79: 

Definition: 


There is no FORTH-79 eguivalent for TRAVERSE . 

: TRAVERSE ( beginning address\direction -- ending address ) 

SWAP BEGIN 

OVER + 7F OVER Cfa) < 

UNTIL 

SWAP DROP ; 



r 


T 


JSet up for BEGIN-UNTILl 
|loo p . j 


Put the address on the 
top of the stack and 
the direction indicator 
second. 


Entry point for the 
branch from the UNTIL . 


Put the direction 
indicator onto the top 
of the parameter stack. 


Aim at the next 
character in the Name 
Field (i.e., address + 
direction indicator). 
Note that if the 
direction indicator is 
a 1, the address will 
advance; but if it is a 
-1, the address will 
decrement. 


This will be used to 
detect the beginning 
or end characters. 


OVER 


C(§ 


< 


UNTIL 


SWAP 


Copy the second 
parameter stack 
value onto the top 
of the parameter 
stack. 


Replace the address 
on the top of the 
parameter stack with 
the 8-bit memory 
contents of that 
address. 


Set up for Cfa) . Get the 
previously calculated 
address. 


This seguentially picks 
up each character in 
the Name Field. 


Replace the top two 
)arameter stack 
;ntries with a true 
Tag (1) if the 
: irst entry < second 
;ntry or a false 

fn\ 

lay \u/.. 



Set truth flag for 
UNTIL . Since both the 
length byte and the 
last character of the 
Name Field are flagged 
with a 80H, all other 
characters will be no 
greater than 7FH. 


< 


Exchange the top two 
values on the 
parameter stack. 


$>( travi) 

Not at end of Name 
Field. Continue 
looping. 

Have now reached one 
end of the Name Field. 
The top of the 
parameter stack now 
contains the address of 
the selected last 
character. The second 
stack entry contains 
the direction 
indicator. 


Put the direction 
indicator onto the top 
of the stack. 
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DROP 


;s 


Drop the t 
from the p 
stack. 

_ 

op value 
arameter 



(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


Drop the direction 
indicator, leaving the 
final address on the 
parameter stack. ___ 
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TRIAD 

TRIAD ( Screen number — ) 

TRIAD outputs three screens to the output device, i-, one page. The page will begin with a screen whose number is divisible by three. 
One of the screens on the page will be the screen specified. 

A message, taken from Line 15 of Screen 4, is listed on the bottom of the page. 

In the 8080 fig-FORTH Version 1.1, pressing any terminal key will terminate the listing. 

* At entry - The top of the parameter stack contains a 16-bit unsigned number specifying one of the screens to be listed. 

* At exit - No parameters. 

TRIAD is a high level colon definition. 

FORTH-79: There is no FORTH-79 equivalent for TRIAD . 

Definition: 


DOCOL 


LIT 

OCH 


EMIT 


TRIAD ( # -) ( 8080 Version 1.1 ) 

0C EMIT 3 / 3 * 3 OVER + SWAP 

DO 

CR I LIST 7TERMINAL IF LEAVE 
LOOP 


THEN 

















7TERMINAL 


IF 


LEAVE 


THEN 


.(TRIA 2 ) 


(LOOP) 


LOOP 


CR 


LIT 

OFH 


Leave a truth flag 
to indicate whether 
or not a terminal 
key has been 
pressed. 


This test is found in 
the 8080 fig-FORTH 
Version 1.1. 


Set up for a possible 
LEAVE . i.e., Terminate 
the listing if a 
terminal key is 
pressed. 


MESSAGE 



TRIA2) 



Make DO-LOOP Limit 
value equal to Index 
value so looping 
will terminate at 
the next occurrence 
of LOOP . 

\ ^ 




Increment the Index 
value. 




Terminal key was 
pressed. Stop listing. 


Entry point for the 
THEN portion of the 
IF-THEN structure. 

J Terminal key was not 
jpressed. 

This execution time 
portion of LOOP is 
compiled into the 
definition by LOOP . 


CR 


*S 


'} 



^(triai) 


Loop back to the DO if 
Index does not equal 
Limit and continue 
looping until all 3 
screens are listed. 

If Index is = or > than 
Limit, do not loop. 
Drop the Index and 
Limit values from the 
return stack. 


{? 


Print the message on 
the bottom of the page 


•} 


Output a c 
return and 
to the out 
device. 

carriage 

linefeed 

DUt 



Place the 
value OFH 
top of the 

stack. 

— 

literal 
onto the 
parameter 


Skip a line. 


Set up to print message 
15. 



Print "FORTH 
INTEREST GROUP - 
MAY 1, 1979" on the 
bottom of the page 
(8080 fig-FORTH 
example). 


Skip a line. 
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TYPE 


TYPE ( beginning address \ number of characters — ) 

TYPE outputs a character string to the output device. No output takes place if the supplied length is zero. 

D.R is an example of a word that uses TYPE . 

* At entry - The top of the parameter stack contains an absolute 16-bit single precision number of characters to be output. 
The second entry contains the 16-bit beginning address of the characters to be typed. 

* At exit - No parameters. 

TYPE is a high level colon definition. 


Refer to COUNT . 


FORTH-79: 

Definition: 


The FORTH-79 equivalent for TYPE is TYPE . 


TYPE ( beginning address\ number of characters — ) 
-DUP IF 

n\/rp + SWAP DO 

I Qa) 

LOOP 


ELSE DROP 
THEN ; 



I 


C(a) 


EMIT 


(LOOP) 


LOOP 


EMIT 



Branch around "false 
portion" (ELSE) of IF 
statement. Count equal 
to zero; no output. 

(This was compiled by 
the ELSE ). 
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ELSE 


This is the entry point 
from the false branch 
of the previous IF . 



i 


DROP 

Drop the top value 
from the parameter 
stack. 

THEN 

. (type 3 )- 

-=5* 


;S 

(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


The count was zero. No 
ouput performed. Drop 
] the unused beginning r 

address pointer. I 


Drop the beginning 
address. 


This is the entry point 
from the "true portion" 
of the IF statement. 
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u* 


u* ( unsigned single multiplier\ unsigned single multiplicand — double unsigned product) 

U* (pronounced "U-star") is an unsigned multiplier. It inputs two unsigned 16-bit values and returns an unsigned 32-bit product. 

The heart of U* (on a processor without a multiply instruction) is a multiply routine which works on the standard "shift and add 
«i~.~~:+u rn ii Tu.r. rjnrfioi r>mHiir»t-c HparivpH whinh are then added tooether to obtain a 32-bit unsigned product. Note that U is 

unsigned. M* should be used if a signed product is desired. 

M* is an example of a word which uses U* . 

WARNING — fig-FORTH U* actually does not multiply unsigned 16-bit values. It only correctly multiplies signed positive 16-bit values. 

* At entry - The top of the parameter stack contains a 16-bit unsigned single precision multiplier. The second stack entry 
contains a 16-bit unsigned single precision multiplicand. 

* At exit - The top of the parameter stack contains the high order 16-bits of an unsigned 32-bit double precision product. 

The second stack entry contains the low order 16-bits of the 32-bit product. 


U* is a low level code primitive. 

Refer to M* . 

FORTH-79: The FORTH-79 equivalent for U* is U* . 



8080 fig-FORTH 
Version 1.1 


NOTE: U* is extremely 
processor dependent so 
actual 8080 
instructions are 
re ferenced. 


Put the multiplier into 
DE. 


Put the multiplicand 
into HL. 


Save the Interpreter 
pointer (IP). 

Temporarily save the 
high order portion of 
the multiplicand. 


Put the low order 
multiplicand into the 
accumulator. 


Multiply the low order 
portion of the 
multiplicand by the 
multiplier. Get a 
24-bit 1st partial 
product. 

Temporarily save the 
low 16-bits of the 1st 
partial product. 


Temporarily save the 
high order byte of the 
1st partial product. 



Put the high order 
multiplicand into the 
accumulator. 


Move the temporarily 
saved high order 1st 
partial into Reg B. 


Multiply the high order 
portion of the 
multiplicand by the 
multiplier. Get a 
24-bit 2nd partial 
product. 


Pop the low order 
16-bits of the 1st 
partial product. 


Make BC contain the 
high order 16-bits of 
the 1st partial 
product. 


Now add the two partial 
products together. 


NOTE this has the 
result of adding: 

HI MID LO (1st) 

+ HI MID LO (2nd) 


32-bit Total Product 

Note that the low order 
8 bits of the 1st 
partial (now in Reg E) 
are not added to 
anything. 

Add low order 16-bits 
of 2nd partial to high 
order 16-bits of 1st 
partial product. 
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HPUSH 


Add any carry to the 
high order 8 bits of 
the 2nd partial, i.e., 
the high order 8 bits 
of the 2nd partial (now 
in the accumulator) 
only have the carry bit 
added to them. 


Move the high order 
byte of the low order 
word to D. (Reg E 
already contains the 
lowest order byte). 

Move the low order byte 
of the high order word 
to L. 


Move the high order 
byte of the high order 
word to H. NOTE: DE 
now contains the low 
order product; HL, the 
high order product. 


Restore IP . 


Push the low order 
product onto the stack. 


Push the high order 
product onto the stack. 


NEXT 


Multiply subroutine MPXY used by U*. 

Given: A - Multiplier 

DE - Multiplicand 

Product returned in: A - High order 8 bits 

HL - Low order 16 bits 
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u 


U. ( value — ) 

U. (pronounced "U-dot") performs an unsigned binary-to-ascii conversion on the 16-bit value on the top of the stack and prints the result 
on the output device followed by one space. 

t-. _ . jl i_•_ Q ACC Sm . . . A am f-krt rmnuoreinn r*oHiv 

I ne current value in dmjl ia uacu ao inc 

U. has the same effect as . but the output is not signed. This is beneficial when displaying 16-bit addresses which have their high order 
bit set, since . prints all addresses above 7FFFH as negative numbers. 

* At entry - The top of the parameter stack contains a 16-bit value to be converted and printed. 

* At exit - No parameters. 

U. is a high level colon definition. 

Refer to . (dot). 

FORTH-79: The FORTH-79 equivalent for U. is U. . 

Definition: : U. ( value --) 

0 D. ; 


DOCOL 


0 


D. 


;s 



Set up for D. by making 
the single precision 
value into a positive 
double precision value. 
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U/ ( unsigned double precision dividend \unsigned divisor — unsigned remainder \ unsigned quotient) 

U/ (pronounced "U-slash") performs unsigned division upon a double precision dividend using a single precision divisor. U/ is the primitive 
division word used by all of the other division words such as M/ , MOD , and M/MOD . Note that U/ performs unsigned division. 

U/ is a low level primitive that executes in the machine code of the host processor. For those processors which have a divide instruction, 
u/ is very straightforward. For processors without a divide instruntinn. imnlp^minn Q 

Division on processors which do not have a divide instruction is usually performed via the "shift and subtract" algorithm. This algorithm 
is conceptually very sirmliar to performing long division by hand. An attempt is made to divide the divisor into the highest order dividend 
column. If the dividend is larger than the divisor, division takes place and a value (1-9 for decimal long division, 1 for binary division) is 
placed in the correspondinq quotient column. If division cannot take place, a 0 is placed in the corresponding quotient column. Division 
of the next dividend column then takes place including any remainder from the previous column's division. This continues until all 
columns have been divided. 

The 8080 implementation of this algorithm can most easily be understood by first looking at the following simplified example. 

In the example in Figure U/-1, 41 (the dividend) is divided by 3 (the divisor). 

Let us envismn that the division is taking place on a simplistic processor that has only two registers. At the start, the high order portion 
of the binary 41 is in Register X and the low order portion is in Register Y. 

Slhce our processor only has two registers, we will develop the quotient in the low order register as the dividend is shifted out. This is 
right ^ acceptable slnce a divid end column (bit) is shifted out to the left while a corresponding quotient column is shifted in from the 

When the division is complete, Register Y contains the quotient and Register X contains any remainder. 

Our processor can subtract 4 bits at a time from the high order portion of the dividend (Register X). Therefore, in order to divide the 
divklend 1Vldend ’ W ° W,U t0 md SUbtraCt both re 9 isters 4 times to completely divide both the high and low portions of the 

mmm iVid fo d iS 41 ° r 29 (hex) or ° 0101 ° 01 binary). At the start, Register X contains the high order portion of "binary 41" 

(0010) and Register Y, the low order portion (1001). 7 

After the first shift left, Register X contains a 5 (0101) and a 0 quotient bit has been shifted into the least significant bit (LSB) of 
Register Y. The divisor, 3, (0011) is then siiitracted from Register X, leaving a remainder of 2 (0010). Since a subtraction was possible, 
the quotient bit is changed from 0 to 1. ' 

J t n e . r .f he second shift left, Register X contains a 4 (0100) and a 0 quotient bit has been shifted into the LSB of Register Y. The divisior, 3 
from 0 to l hen Sll)traCted from Register x > having a remainder of 1 (0001). Since a subtraction was possible, the quotient bit is changed 

After the third shift left, Register X contains a 2 (0010) and another 0 quotient bit has been shifted into the LSB of Register Y. An 
? ,s tben ™ ade *° subtract the divisior, 3 (0011), from Register X; but since 3 is larger than 2, a subtraction cannot be made. 

1NU IL: In the actual algorithm, the subtraction is always performed and if underflow is detected, the divisor value is added back to the 
dividend.) The value 2 (0010) is left in Register X and the corresponding quotient bit in Register Y remains a 0. 

After the fourth shift left, Register X contains a 3 (0101) and another 0 quotient bit has been shifted into the LSB of Register Y. The 
divisior, 3 (0011) is again siitracted from Register X, leaving a remainder of 2 (0010). Since a subtraction was possible, the quotient bit 
is changed from 0 to 1. ^ 

Since four shifts have occurred, the division is complete. Register Y contains the quotient, 13 decimal (1101); and Register X contains 
the remainder 2 decimal (0010) — which is the correct answer obtained by dividing decimal 41 by 3. 


START 


REG X 


0 10 1 
1 1 

0 0 10 

0 10 0 
1 1 

0 0 0 1 

0 0 10 
1 1 


REG Y 
10 0 1 
0 0 10 
0 0 11 
0 110 
0 111 
1110 


41 / 3 = 13 rem 2 


0 10 1 
1 1 

0 0 10 


110 0 
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Figure U/-1 

Example of "Shift-Subtract" Division Algorithm 



Once the example is understood, the actual 8080 implementation of the algorithm is also understandable. Registers DE contain the low 
order dividend. This corresponds to Register Y in the example. Registers HL contain the high order portion of the dividend. This 
corresponds to Register X. As in the example, registers DE will contain the quotient and registers HL will contain the remainder. The 
divisor is kept in registers BC. 


The register pair DE is 16-bits wide, therefore 16 shifts will be performed. 


When the routine is first entered, a check is made to determine if the divisor is larger than the dividend. If so, both remainder and 
quotient are set to FF (hex) and the routine is exited. 


Otherwise, a loop counter is initialized to shift 16 times and the shift-sub tract sequence begins. A 32-bit double precision shift is 
performed between registers DE and HL. If a carry bit is shifted out, it is known absolutely that a subtraction could occur without true 
underflow so the divisor (BC) is subtracted from the high order dividend (HL). (Any underflow in this case would simply be a remainder 
with a borrow occurring from the carry.) If a carry bit is not shifted out, an underflow occurrence would mean that subtraction could not 
take place, so a separate subtraction routine is executed (although the identical function is performed, i.e., the divisor is subtracted from 
the high order dividend). The difference with this routine is that it checks for underflow and if detected adds the previously subtracted 
divisor back to the dividend. The quotient value is decremented by 1 so that when the automatic quotient increment is executed it will 
be the same as if no increment were performed. (NOTE: This decrement is just a programming "trick" and has nothing really to do with 
the algorithm. The intent is to set the quotient bit to 1 for a successful subtraction or to 0 for an un-successful subtraction.) 


This shift-sub tract is performed 16 times. At that time, the quotient is in register DE and the remainder is in HL. 

* At entry - The top of the parameter stack contains an unsigned 16-bit single precision divisor. The second and third stack 
entries contain an unsigned 32-bit double precision dividend. (Note that some fig-FORTH implementations require a 
31-bit positive signed vlaue.) The second stack entry contains the high order portion of the dividend; the third, the low 
order portion. 

* At exit - The top of the parameter stack contains an unsigned 16-bit single precision quotient. The second stack entry 
contains the unsigned 16-bit remainder from the division. 


U/ is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for U/ is U/MOD . 

Note that this is an extremely processor-dependent routine and therefore the flowchart often references the 8080 instruction set. 


GD 


8080 fig-FORTH 
Version 1.1 


f Individual instructions 
I may be placed together 
J in some instances so 
^ that the logic of the ^ 
■ algorithm may be more ■ 
easily conveyed. 

("Get the operands from"l 
the stack and put them f 

- J 


into registers. 


LXI H,4 
DAD SP 

_ 



Swap the IP (into 
memory) with the low 
order portion of the 
dividend (DE). 


POP B 



Incrementing the stack 
pointer by 4 aims at 
the low order portion 
of the dividend. 


Put the 16-bit divisor 
into BC. 



Exit. 
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Initialize loop 
counter for 16 
shifts. 



(USLA2)- 


Now perform a double 
precision 32-bit shift 
« of HL and DE. Shift the > 
highest order dividend 
bit into the carry. 


DAD H 



RAL 



Add the contents of HL 
to itself to effect a 
16-bit wide shift 1 bit 
to the left. 

Temporarily save the 
carry bit for future 
subtract. NOTE: If 
carry is one, no 
underflow can occur. 



Now shift the low order 
portion of the dividend 
one bit left too. 


Branch if no carry bit 
shifted out. 


Else, "shift" the carry 
bit into the high order 
portion of the 
dividend. 


Swap high and low 
portions of dividend 
back, i.e., 

DE = Low 
HL = High 


Restore previously 
saved carry. 



< 


Examine the carry bit. 
If it is 1, then 
subtracting the 
divisior from the 
dividend cannot cause 
underflow. (Even if 
underflow occurs, it 
would not be true 
underflow because a 
"borrow" could have 
occurred from the set 
carry bit). 




-^(uslm) 


Branch if no carry. The 
subtraction must take 
into account that 
underflow can occur. 
Else, simply subtract. 



HPUSH Put the remainder on 

the second stack entry. 


DPUSH Put the quotient on the 

top of the stack. 

NEXT 
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UNTIL 


UNTIL 

COMPILE TIME (Sequence 2): ( loop address \ 1 — ) 

EXECUTION TIME (Sequence 3): ( truth flag — ) 

UNTIL is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution 
time. 

UNTIL is used to mark the end of an indefinite, conditional loop structure where repetition continues "until" the boolean input to UNTIL 
is true. 

UNTIL is used in the form: 


BEGIN "Loop Body" UNTIL 

( END may be used in place of UNTIL but UNTIL is the preferred word.) 

BEGIN-UNTTL structures must always be used within a colon definition. 

It is important to note that in using a BEGIN-UNTIL structure, the "loop body" will always be executed at least once. This is because the 
exit condition is not tested "until" after the "loop body" has been executed. This is known as a "post-test" loop. If the exit condition 
must be tested before "loop body" execution, the BEGIN-WHILE-REPEAT structure should be used instead. 

The compile time action of UNTIL is to compile a OBRANCH into the dictionary. Secondly, it resolves the "loop body" entry point 
address provided by BEGIN into a return branch offset used by the OBRANCH and stores this offset into the definition. 

Some compiler security is provided by checking for a 1 on the top of the stack. An UNTIL without a preceding BEGIN will probably not 
encounter a 1 on the top of the stack. (During compilation, BEGIN leaves a 1 on the top of the stack.) 

The execution time action (Sequence 3) of UNTIL is to provide a conditional repetitive branch back to the loop's corresponding BEGIN 
(i.e., the beginning of the "loop body"). The input parameter to BEGIN is a boolean flag. If this flag is false (0), control returns to the 
first word in the "loop body" (just after BEGIN ). If the boolean flag is true (not D), no branch occurs and the loop is exited. That is, 
repetitive looping continues "until" the exit conditional is true. 

The OBRANCH, compiled into the definition at compile time, is what controls the looping. 

Note that UNTIL is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 

BLOCK is an example of a word which uses UNTIL . 


COMPILE TIME (Sequence 2): 

* At entry - The top of the parameter stack contains the 16-bit signed single precision value 1 used for compiler security. 

The second stack entry contains the 16-bit entry point address of the "loop body" portion of the BEGIN-UNTIL structure. 

* At 6Xit — No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - The top of the parameter stack contains a 16-bit signed single precision boolean flag used to control the 
conditional looping of the structure. 

* At exit - No parameters. 

LIKELY ERROR MESSAGES: 

COMPILATION ONLY (11H) — This word may only be used within a colon definition. 

CONDITIONALS NOT PAIRED (13H) — There is some sort of problem with the pairing of conditionals within the definition being 
compiled. 

UNTIL is a high level colon definition. 

Refer to BEGIN , OBRANCH , and END . 

FORTH-79: The FORTH-79 equivalent for UNTIL is UNTIL . 

Definition: : UNTIL ( loop address \ 1 — ) ( compile time ) 

1 7PAIRS COMPILE OBRANCH BACK ; IMMEDIATE 
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COMPILE TIME action of UNTIL : ( loop address \ 1 — ) 
(Sequence 2) 


EXECUTION TIME action of UNTIL : ( truth flag — ) 
(Sequence3) 


DOCOL 


1 


7PAIRS 


COMPILE 


0 BRANCH 


BACK 


;S 


IMMEDIATE 



Set up for 7PAIRS . 


A preceding BEGIN will 
have left a 1 on the 
stack. If the UNTIL is 
missing (i.e., the 1 is 
missing) issue an error 
message and QUIT. _ 


This puts OBRANCH into 
the definition being 
compiled (Sequence 2). 


OBRANCH executes at 
Sequence 3, not at 
compile time (Sequence 
2 ). 


The address left by 
BEGIN is used to 
calculate a return 
branch offset. This 
offset is then compiled 
into the definition and 
referenced by 
OBRANCH at execution 
time (Sequence 3). 


UNTIL is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


BEGIN 

f Droi nnD L* 



Entry point to 
beginning of "loop 
body". 

l dtLaLUUr j 

1 

! 


"Loop Body". 

Do whatever processing 
is needed for the "loop 
body" and then set up 
boolean truth flag on 
the top of the stack. 




OBRANCH 

OBRANCH is the run 
time portion of UNTIL . 



Branch back to 
beginning of "loop 
body" using the 
previously calculated 
and stored backward 
offset. 


Exit from the loop 
and continue to the 
next definition. 
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UPDATE 


UPDATE ( - ) 

UPDATE flags the most-recently-accessed buffer so that the buffer's data will be written to mass storage when that buffer is 
re-allocated or the word FLUSH is executed. The update bit (or flag) is the most significant bit (MSB) of the header, (i.e., The block 
number portion of a buffer.) Refer to +BUF for a detailed description of the buffers and their organization. 

The intent of UPDATE is to flag the data contained within a buffer as being changed or modified. Note, however, that it is perfectly 
legal to UPDATE a buffer that has not been modified although this action may cause an unnecessary write of information that is 
identical to that already on the disk. 

It is extremely important to note, that the simple act of modifying data in a buffer will not cause it to be written back to disk. The 
update flag must be set in order for this to occur. 

It is also equally important to note that setting the update flag does not absolutely guarantee that data will be written to disk. This 
write only occurs when a buffer is allocated. If the system is restarted, or powered off, or the desired disk is removed from the drive; 
the data will not be written to the desired location. This problem is easily solved by using the word FLUSH to force all updated buffers 

to be written to disk before allowing any of the conditions mentioned above to occur. 

UPDATE should always be executed at the end of a sequence which modifies data in a buffer. "Updating" a buffer more than once does 

no harm and takes very little execution time; especially in comparison to writing the data to disk each time a change takes place. 


* At entry - No parameters. 

* At exit - No parameters. 

UPDATE is a high level colon definition. 

Refer to +BUF , BLOCK , USE , EMPTY-BUFFERS , and FLUSH . 
FORTH-79: The FORTH-79 equivalent for UPDATE is UPDATE . 


Definition: 


DOCOL 


PREV 


LIT 

8000H 


OR 


UPDATE 

PREV 


(-) 



8000 OR PREV fa : 


PREV 


Set up for (3 . PREV 
contains the address of 
the most recently 
accessed buffer. 


Pick up the address of 
the most recently 
accessed buffer. 


Set up for OR . Pick up 
the header portion of 
the buffer. 


Set up for OR . 8000H 
is a logical mask which 
will turn on the update 
flag if it is not 
already on. 


Set the update bit to a 
1. i.e., Turn it on. 


;s 



Set up for (3 . PREV 
contains the address of 
the most recently 
accessed buffer. 


Set up for 1 . Again 
get the address of the 

b i i-f-for* ii iof flonnorl oe 

updated. 


Store the header 

portion, including the 
set update bit, back 
into the buffer. 
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USE 

USE ( — data address ) 

USE is a system variable which contains the address of the buffer to "use" next. USE is referenced by buffer allocation routines. 

USE is described in detail in the description of BUFFER and +BUF . (Note that USE is a system variable and not a user variable.) 

In the fig-Model, USE is normally initialized to point to FIRST (the first buffer). This is done by using the "initial value" feature of the 
word VARIABLE (e.g., BUF1 VARIABLE USE). Although this technigue works, it is not good programming practice and in the 8080 
fig-FORTH Version 1.1 USE is initialized by COLD . 

The system variable USE is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the system variable USE . 

Refer to BUFFER , +BUF , BLOCK , and VARIABLE . 

FORTH-79: There is no FORTH-79 equivalent for USE . 
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USER 


USER 


COMPILE TIME (Sequence 2): ( offset - ) 
EXECUTION TIME (Sequence 3): ( — address ) 


USER is a defining word and therefore exhibits two different sets of actions; those at compile time and those at run time. 


USER 's compile time (Sequence 2) actiun is to define a user variable. A user variable is a 16- 
pointer, UP ) for this user variable. (The value of the offset may not be greater than 255 decimal.) 


The form of a defined user variable is: 


n USER cccc 

where n is the variable's offset from the beginning of the user area and cccc is the name of the variable. 

The compile time result of USER is a definition structured like this: 

Name Field 
Link Field 

Code Field - Run Time Code of USER 
Parameter Field - Offset Value 

USER variables play a very important role in multitasking FORTH systems; however, in non- multitasking systems they could simply be 
replaced by variables. 

Every task in a multitasking environment has functions that are common with other tasks. That is, the system must keep track of each 
task's base (BASE), its input text buffer pointers (IN), its compilation state (STATE), etc. The simplest way to solve this problem is to: 

1. Write routines which perform specific functions for any task. 

2. Make these routines access task specific data via a name (i.e., a user variable) . 

3. Make the execution time code (Sequence 3) for a user variable use the contents of the user area pointer (UP) as a base to which 
the user variable offset is added. 

4. Assign each task a separate user variable area and simply "aim" the user area pointer at the user area of whatever task is 
active. 


TASK 1 TASK 2 TASK 3 


User 

Variable 

Area 

1 


User 

Variable 

Area 

2 


User 

Variable 

Area 


UP is changed to point to the active task's user area. 

User variables are usually initialized at system start up time by COLD with initialization data stored in the Origin Parameter Area. 
(Refer to COLD). 

The execution time (Sequence 3) action, when the named variable is referenced, is to place the absolute address (offset + beginning 
address) of the 16-bit variable location onto the top of the parameter stack. 

COMPILE TIME (Sequence 2): 

* At entry - The top of the parameter stack contains a 16-bit offset value. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the absolute address of the user variable location. 

LIKELY ERROR MESSAGES: 

DICTIONARY FULL (2) — The dictionary has grown into the Terminal Input Buffer. 

DEFINITION NOT FINISHED (14H) — The position of the parameter stack pointer is not the same as it was when this definition started 
being compiled. Something is wrong with the definition. 

USER is a high level colon definition. 

FORTH-79: USER is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". 

Definition: : USER ( offset —) ( compile time) 

CONSTANT ;CODE 

Note: The assembly language execution time code follows the ;CODE . 
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COMPILE TIME action of USER (Sequence 2)j ( offset — ) 


EXECUTION TIME action of USER (Sequence 3): ( — address ) 


Note: This code physically follows ;CODE in the source code for 
USER. 


DOCOL 


CONSTANT 


(;CODE) 



In compiling, USER 
actually creates a 
CONSTANT and then 
overlays the CONSTANT 
run time CFA with the 
run time code for 
USER . 


Now overlay the OF A 
for the run time code of 
CONSTANT . 

(;CODE) was compiled 
into USER by ;CODE 
when USER was 
compiled. 



HPUSH Push absolute address 


onto the top of the 
parameter stack. 


NEXT 












VARIABLE 


VARIABLE 

COMPILE TIME (Sequence 2): ( n — ) 

EXECUTION TIME (Sequence 3): ( - address ) 

VARIABLE is a defining word and therefore exhibits two different sets of actions; those at compile time and those at execution time. 

A VARIABLE in FORTH has the same effect as a variable in most other computer languages. That is, a label is assigned to a specific 
memory location. Any future references to that location can then be performed via the assigned name. VARIABLE does differ from 
nther lanauaaes in that it is active. The equating of a name to an address is not just an action of a compiler or assembler during compile 
time. Instead, the execution time code for VARIABLE actively places the address of the variable onto the top of the parameter stack. 

The compile time action (Sequence 2) for VARIABLE is to create a definition containing the variable name, a pointer to the execution 
time code for variable, and the 16-bit location. One definition is created per variable name. VARIABLE is used in the form: 

n VARIABLE cccc 


where n is the variable's initial value and cccc is its assigned name. 

Note: Although it is possible to specify at compile time (Sequence 2) the initial value of a variable, it is a much safer programming 
practice to always initialize variables during program initialization. 

The execution time (Sequence 3) action of VARIABLE, when the variable name is referenced, is to place the address of the named 16-bit 
location onto the top of the parameter stack. 

COMPILE TIME (Sequence 2): 

* At entry - The top of the parameter stack contains a 16-bit value. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3): 


* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the variable location. 


LIKELY ERROR MESSAGES: 


DICTIONARY FULL (2) — The dictionary has grown into the Terminal Input Buffer. 


DEFINITION NOT FINISHED (14H)_The position of the parameter stack pointer 

being compiled. Something is wrong with the definition. 


is not the same as it was when this definition started 


VARIABLE is a high level colon definition. 

FORTH-79: The FORTH-79 equivalent for VARIABLE is VARIABLE , although in FORTH-79 no initial value may be specified at compile 
time. 

Definition: : VARIABLE ( n - ) ( compile time ) 

CONSTANT ;CODE 

Note: The assembly language execution time code follows the ;CODE . 
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COMPILE TIME action of VARIABLE : ( n - ) 

(Sequence 2) 

NOTE: The execution time (Sequence 3) code for VARIABLE 
physically follows the ;CODE in the source code for VARIABLE . 


EXECUTION TIME action of VARIABLE : ( - address ) 
(Sequence 3) 


DOCOL 


CONSTANT 


(;CODE) 



In compiling, VARIABLE 
actually creates a 
CONSTANT . 
CONSTANT then 
inputs the initial 
variable value and 
compiles it into the 
definition. 


The only difference 
between a CONSTANT 
definition and a 
VARIABLE definition is 
the address of the 
execution time 
(Sequence 3) code. This 
changes the CEA from 
CONSTANT to 
VARIABLE . 


(variable) 


Aim at variable 
location. 


HPUSH Push the address onto 

the top of the 
parameter stack. 


NEXT 


[Aim at the Parameter 
Field (PFA) of 
definition being 
executed. 
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VLIST 


VLIST ( -) 

VLIST (pronounced "V-list") lists the names of all of the definitions in the CONTEXT vocabulary onto the output device. 

Pressing any terminal key will terminate the listing. Basically VLIST works by finding the end definition in the CONTEXT vocabulary and 
then chaining completely through the vocabulary via a BEGIN-UNTIL loop. Inside this loop, ID. is used to print each definition name. 
The output format of a VLIST generally varies between specific FORTH implementations. 

* At entry - No parameters. 

* At exit - No parameters. 

VLIST is a high level colon definition. 

FORTH-79: VLIST is not explicitly defined by FORTH-79 but it is listed in the "FORTH-79 Referenced Word Set". 

Note that although this flowchart for VLIST is long, no high level flowchart accompanies it because its logic is straightforward. 

CONTEXT fa) fa! 


Definition: 


DOCOL 


LIT 

80H 


CONTEXT 


§ 


VLIST ( - ) 

80 OUT I 
BEGIN 

OUT (3 C/L > IF CR 0 OUT I 
DUP ID. SPACE SPACE PFA LFA 
DUP 0= 7TERMINAL OR 
UNTIL DROP ; 


THFN 



Aim at the top of the 
CONTEXT vocabulary. 
Set up to VLIST down 
from the top of the 
CONTEXT vocabulary. 


This is the entry point 
for BEGIN portion of 
BEGIN-UNTIL 
structure. 

Start VLISTing. 

Note: One definition 
name is output per loop 
through the 
BEGIN-UNTIL loop. 

r n 

ISet up to determine if I 
I are at end of line. [ 

Set up for (a) . 


Set up for > . Pick up 
the character count of 
characters output so 
far. 


Set up for > to 
determine if at the end 
of output device line 
yet. 


Set up for IF and start 
another line if past 
end of the present one. 
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CR 


0 


OUT 


THEN 

.(vus2 y 


DUP 


ID. 


SPACE 

SPACE 


PFA 


304 



Determine if are at end 
of line. 




_ 

Output a c 
return and 
to the outp 
dev ice. 

arriage 

linefeed 

)Ut 



Place the constant 0 
onto the top of the 
parameter stack. 



Place the address of 
the user variable 

OUT onto the top of 
the parameter stack. 



Store the s 

16-bit valu 

the spec if i 

location. 

— 

pecified 
e into 
ed memory 

— 


Branch around "true 
portion" of IF 
statement (i.e., are 
not at end of line). 


Else set up for another 
line. 


Start a new line on the 
output device. 


Set up for I 


Set up for 1 


Reset OUT to 0. i.e., 
The beginning of a new 
line. 


This is the entry point 
for the THEN portion of 
the previous IF 

{ Branched here . 
yet at end of line. 


5 if not! 
line. | 


Duplicate 
16-bit valu 
parameter 

_ 

the top 
e on the 
stack. 



Output the name of a 
definition from the 
specified address. 



Output an 
blank to th 
device. 

ascii 
e output 

— 


Set ip for ID. . 
Duplicate the Name 
Field Address presently 
on the top of the 
stack. 


Print the name of the 
definition at which 
presently aiming. 

This actually is what 
does the printing! 


Space two spaces 
between names. 


Chain to the next 
definition. 


*} 


Convert the Name 
Field Address on the 
top of the parameter 
stack to the 

Parameter Field 
Address of the same 
definition. 

Set up for LFA . Use 
the Name Field Address 
presently on the top of 
the stack to get the 
Parameter Field 

Address. 




LFA 




DUP 


0 = 


7TERMINAL 


OR 


UNTIL 


DROP 


;s 

















VOC-LINK 


VOC-LINK ( — data address ) 

VOC-LINK (oronounced "voke-link" for vocabulary link) is a user variable that contains an address that points to a field in the vocabulary 
^ . . j P) n nnt . p nn fii S p VOC-LINK with the vocabulary pseudo link field. This voc-link field in the 

voc-link chain. 


VOC-LINK is described in more detail in the description of VOCABULARY . 

VOC-LINK is initialized by COLD during system startup with data from the origin parameter area. 

The user variable VOC-LINK is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 

* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable vuu-lINK . 

Refer to VOCABULARY , FORTH , and USER . 


FORTH-79: There is no FORTH-79 equivalent for VOC-LINK . 
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VOCABULARY 

VOCABULARY 

DEFINITION TIME (Sequence 1): ( — ) 

COMPILE TIME (Sequence 2): ( — ) 

EXECUTION TIME (Sequence 3): ( — ) 

VOCABULARY IS a flfifininn u/nrrl anH fhorofono avK!KU A j:fr_ k _ x- _ _. .. . . . 

compile time, and those’at executi^,'tirn^r“““ UIMt ’"" ,t SBU ‘ ° T aCUOn8? tnose actlons at definition time > those actions at 
The definition time action of VOCABULARY is to create the word VOCABULARY (a "parent" definition). 

h'eaVorTilt enTry a of“ 0 new v^bTry^ ’* l ° 3 vocabular '' h 6 "" 111 ™ definitions). These definitions then serves as the 

C0ynST U %hL m p e ffpoiTf°,L V0C f aULAR I ‘ S t0 st ° re th ! addrass of that voc ebuiary's "Vocabulary Link Pointer" into the user variable 
to -FIND V 18 CaUSe nam vocabulary to be searched first whenever a dictionary search is performed. (Refer 


The purpose of VOCABULARY is best understood by first understanding the use of vocabularies by FORTH in general. 

fhe'ToUoiaZ” ‘ S t£* T* by F0RTH “ “T* the SCOpe of 3 narna b * I “ tric0n 9 dictionary searches to a specified subset of 

the thctionary. This abd ty to make names non-globai is common among high level languages as can be seen in the "scoping" rules in 
ALOUL, PASCAL, and PL/1, where a routine's internal variables are inaccessible to higher-level routines. In FORTH, however the 
programmer must explicitly hide" words using vocabulary names in conjunction with the word DEFINITIONS . 

Each word in the dictionary is actually identified by two names: 


1. The word’s vocabulary name/branch name (analogous to its surname or family name). 

2. The word's definition name (analogous to its given name). 


If a definition name is unique throughout the entire dictionary, only the definition name is necessary to identify the word. However if 
there is more than one definition with the same name, the vocabulary name must also be used. ’ 

vocabulary 68 ^ as , two-dimensional branches of a tree structure with the main trunk being the FORTH 

pfiniSmgvh IT? V0 T 1 * ) A " y SingIe vocabular y branch may be the "parent" to any number of "child" branches. A new 

definition may be appended at any time to the end of any vocabulary. 

bran ? hes are what make scoping possible. Vocabularies cause the one-dimensional dictionary to be searched in a loqically 
imensional ° rder * T IS vocabuIar y " tree " * searched inwardly (traversed) in one direction from the last definition of the specified 
•wit" 7n T h a ? th w T", ° f the tFee (the F0R ™ vocabular y)- The search proceeds in a direct line from "Siild" to 

witWn the'scop'e search. 0< (Refer To Figure VOC-l'J 601 “ " 0t SBBrChBdi thBrBf ° re ’ bba ™ a "= 


IZ’Z Start - t0 bBC0 T apparenl whan one attem Pts to implement this two-dimensional tree structure 

into the l-ORTH dictionary. The dictionary is a one-dimensional stack, allocated with one dictionary pointer (DP). Therefore this 
two-dimensional tree structure must be logically built and maintained within a one-dimensional environment (the dictionary). 

The logical vocabulary tree structure must support several functions: 


1. A mechanism must exist to allow a "child" vocabulary to be created and appended to its "parent" vocabulary. 

2 ' definition^o'the'emi'of the*dicti(xiary n "stack 1 *) de,i " iti °" '° Bnd ° f B " y V °° abulary wWlB actuall >' ph * aiaal * a PP a " b >"9 tba 


3. 


4. 


Vocabularies must be chained so that a dictionary search proceeds inwardly through the "child" to the "parent” vocabularies. 


It must be possible to specify (i.e., name) both the vocabulary to which a new definition is 
separate vocabulary which contains the words to be used in creating the new definition. 


to be appended and a possibly 


Fiaure th ® ?? the " Vocabular y Link FieId " P^ter contained in the VOCABULARY definition. (Refer to 

I nk Fi!2 C r<, 2 * I h 8 exactly the same purpose as the Link Field in other definitions. Note, however, that this Vocabulary 

c^taK^'aSr^Z^derr" 16 '" ^ °' VOCABULARY * * «* to be effused with t’he normal iSTES 


^ h Z,Zu^ r a™ B V L ao R v Y Z/ m i ti0n createb < refer to Figure VOC-3), this pointer is initially linked to the Pseudo Name Field in its 
WfiFlle ScaTy U ? nk)dt !tf^;en? m r thB ' Llnk RB ‘ d8 BlWayS P ° int “ NamB FialdsJ Thls satlsflas the tequirement that a 

When a definition is first appended to this newly created vocabulary (refer to Fiaure VOC-4) CRFATF rnnioc iho nninip. * 

ReTd b o U J a t r h y e L ne nk T T^ ^ ^ ^vSEl^ifnk Reld^the^S t^poTnlto th^™ 

I? Hioti 1 " f y - T, , 9 ?l neW int0 the vocabulary chain. As new words are physically added to the end of 

r^link^^^^hem^Tn ? V the end ° f thiS (the " current " vocabulary) chain and the Vocabulary Link Field °s 

point to the iT; f W °h • “hT" def ‘T° nS a L e a PP ended t0 the vocabulary, the vocabulary link pointer is altered to always 

point to the last (latest) word in the vocabulary. This satisfies the requirement that definitions be physically added to the 
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one-dimensional dictionary while being logically linked in a two-dimensional tree structure. The link between "child" and "parent" is still 
preserved. Note that the normal header linkages are used to link the newly created vocabulary definition into the one-dimensional 

dictionary "stack". 

Another reouirement is that searches must proceed inwardly through the "child" to the "parent" vocabularies. When searching, -FIND 
first examines the Name Field of a definition for a character string match. If there is no match, that definition's L.inK rieia is usea to 
obtain the Name Field Address of the next definition "up" the chain where the comparison is performed again. The vocabulary definition 
is structured such that it takes advantage of -FIND's characteristic of continuing the search if a name match is not found. .he Pseudo 
Name Field" is actually a perfectly legal and valid but impossible name. (Refer to Figure VOC-5.) This Name Field is followed by a valid 
"Link Field" which points to the last definition in that vocabulary. If a "child" vocabulary is searched for a word which it does not 
contain, the search will continue until the topmost definition is reached. The Link Field of this definition, as previously stated, points to 
the Pseudo Name Field of the "parent" vocabulary. Since there is no match, -FIND then examines the Pseudo Name Field of the P^ent 
vocabulary definition. Since this Name Field contains an ascii blank, which by definition is an impossible name; no match is found and 
the contents of the following Vocabulary Link Field is then fetched. -FIND has been "tricked" and never "realizes" that the Pseudo Name 
Field and the Vocabulary Link Fields are not common header Name Fields and Link Fields. Since the Vocabulary Link Field always points 
to the latest definition in the vocabulary, tne searcn is continued at the uouum ui L ..c -.a. 

has proceeded inwardly from the "child" to the "parent". This chaining through vocabularies wiii continue until a cnaracter match or nun 

Link Field is encountered. 

The Vocabulary Link Field is also the means by which it is possible to specify to which vocabulary a definition is to be appended and 
which vocabulary is to be searched first when creating a definition. To do this, two additional pointers are used: the user varia les 
CURRENT and CONTEXT. These two variables contain pointers to Vocabulary Link Fields. 

The CURRENT pointer is used by CREATE and is set to point to the vocabulary into which definitions are "currently" being appended. 
The CONTEXT pointer is set to point to the vocabulary which should be searched first. ( -FIND first picks up the contents of CONTEXT 
which is aiming at a Vocabulary Link Field that in turn is always aiming at the "latest" word of that vocabulary. If -FIND has not found a 
match by the time it encounters a null link, usually the end of the FORTH vocabulary; then the address in the CURRENT pointer is 
fetched and the search is repeated starting at the bottom of the CURRENT vocabulary.) 


CONTEXT is set by naming a previously defined vocabulary thereby executing the run time portion of VOCABULARY. 

The execution time action (Sequence 3) of VOCABULARY is to store the address of that vocabulary's "Vocabulary Link Pointer" into the 
user variable CONTEXT . This causes the named vocabulary to be searched first whenever a dictionary search is performed. 


This makes for very readable FORTH programs because simply stating the name of a vocabulary "automatically" makes it the vocabulary 
to be searched first. 

It should be noted that CONTEXT simply denotes which vocabulary is to be searched first (i.e., sets the search scope). This means that 
its use is not limited to only specifying which vocabulary is search first when creating new definitions. It can also be used to specify 
which definitions are to be executed. For example, the EDITOR vocabulary contains words used for editing. Stating EDITOR causes the 
EDITOR vocabulary to be searched, thereby allowing editing commands to be found and executed. 

CURRENT is set via the word DEFINITIONS . DEFINITIONS copies the contents of CONTEXT into CURRENT . This then is what 
determines onto which vocabulary "definitions" are to be appended. The compile time action of : is to copy the contents of CURREN 
into CONTEXT . This makes the vocabulary to which definitions are being apprended also the first vocabulary to be searched, mere is 
no special reason why colon does this except that it is common practice to append to and search from the same vocabulary. 

For example: VOCABULARY TOAD creates a linked vocabulary definition named TOAD . Later execution of TOAD causes CONTEXT 

to be set so that dictionary searcning win begin with .o, .-..e ~ - -- . , .. ..._ 

CURRENT . i.e., TOAD will have definitions appended to it as well as being searched first. Execution of : when compiling a definition 
causes CURRENT to be set to CONTEXT. Naming another vocabulary within the definition, such as FROG, would cause rKUG to e 
searched first but definitions would still be appended to TOAD (because of the previous DEFINITIONS ). 


One additional "pointer", a definition named LATEST , also makes use of the fact that the Vocabulary Link Field always points to the 
last, i.e., "latest", definition added to a vocabulary. (See LATEST .) LATEST is used to obtain the address of the last definition 
compiled. It does this by performing an indirect fetch through CURRENT . 

Note that CURRENT and CONTEXT are indirect pointers (i.e., to obtain a definition address, two fetches must be performed). The 
contents of the variable must be fetched to point to the Vocabulary Link Field. Then secondly, the contents of the Link Field must be 
fetched to point to the definition itself. 

As shown in Figure VOC-1, there is one other pointer contained within the vocabulary definition: the "Chronological Link Pointer’'. 
When a vocabulary definition is compiled (Sequence 2), the "Chronological Link Pointer" is aimed at its corresponding location in the 
previously created vocabulary definition. This causes all vocabularies to be chronologically linked together in the order they were 
created. The "Chronological Link Pointer" of the definition being created is filled with the contents of the user variable VUC-L1N . 
VOC-LINK is then stuffed with the address of the "chronological link pointer" of the definition being created where it can then be used to 
link the next vocabulary definition into the chain. 


Some versions of fig-FORTH use this pointer to allow forgetting through multiple vocabularies. WARNING! When multiple vocabularies 
have been created, the use of the normal fig-Mcdel FORGET produces indeterminable results and will probably cause an eventual system 
crash. Refer to FORGET . 
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Name Field _ _ _ __ 

_ _ _ Name of vocabulary 

(e.g., EDITOR) . 



Link Field. _ _ _ 

_ _ _Link to next definition 

in dictionary. 



Code Field _ _ _ _ 

_ _ _ Pointer to run time 


/ 


portion of DOES> . 



CFA 

_ _ _ Pointer to run time 

portion of VOCABULARY 

Parameter ^ 


Pseudo Name Field 

A081 

_ _ _ Impossible but legal 
name. 

Field 


Vocabulary Link_ __ 
Field 

_ _ _Link to latest definition 

in this vocabulary. 
Referenced via LATEST . 



Chronological Link. _ 
Field 

— — — Pointer to previously 
created vocabulary. 


Referenced via VOC-LINK 


Figure VOC-1 

Structure of a VOCABULARY Definition 








I 


I FORTH 



Figure VOC-2 

Logical and Physical Vocabulary Linkage 
(Reprinted by permission of Kim Harris) 








"Child" 


"Parent" 


NF 
LF 
CF 
CFA 
PNF 
VLF ■ 

CLF 

Figure VOC-3 

The newly created "child" vocabulary definition is linked to its "parent" vocabulary definition. 

"Parent" 

NF 
LF 

CF To "Grandparent" 

CFA 
PNF 
VLF 
CLF 

1. The "child's" Vocabulary Link Field is copied into the Link Field of the new definition. This links the "child's" definition to the 
"parent's". 

2. The "child's" Vocabulary Link Field is then aimed at the new definition's Name Field. This links the "child" to its definitions. 

Figure VOC-4 

Adding a Definition to a Vocabulary. 


End of Name Field Flag- 

Data Byte (Hex 20) 
i.e., a blank 

-^80 

+ 20 

80 

+ 01 

-Start of Name Field Flag 

Name Field is 1 Char Long 


A0 

81 



This is an "impossible" Name Field since the Interpreter ignores blanks, therefore a blank cannot normally be the name of a definition. 
NOTE: Bytes are swapped in the 8080 when stored in memory. A081 will be 810A when in memory. 



"ChildVs" 

Definition "Child" 



CLF 
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Figure VOC-5 

Structure of the Pseudo Name Field 



DEFINITION TIME (Sequence 1) - When VOCABULARY is created: 


* At entry - No parameters. 

* At exit - No parameters. 

COMPILE TIME (Sequence 2) - When VOCABULARY is used to create a vocabulary definition: 

* At entry - No parameters on the parameter stack; however, the word VOCABULARY must be followed by a character 
string specifying the name of the vocabulary to be created. 

* At exit - No parameters. 

EXECUTION TIME (Sequence 3) - When the definition created via VOCABULARY executes: 

* At entry - No parameters. 

* At exit - No parameters on the parameter stack; however, the user variable CONTEXT will be pointing to the Vocabulary 
Link Field in the named vocabulary's definition. 

LIKELY ERROR MESSAGES: 

DICTIONARY FULL (2) -- The dictionary has grown into the Terminal Input Buffer. 

DEFINITION NOT FINISHED (14H) — The position of the parameter stack pointer is not the same as it was when this definition started 
being compiled. Something is wrong with the definition. 

VOCABULARY is a high level colon definition. 

Refer to CONTEXT , CURRENT , DEFINITIONS , LATEST , FORTH , VOC-LINK . -FIND , and FORGET . 

FORTH-79: The FORTH-79 equivalent for VOCABULARY is VOCABULARY . Note, however, that the structure of vocabularies differs 
from the fig-FORTH Model. Refer to the FORTH-79 Standard. 

Definition: : VOCABULARY ( -) 

<BUILDS 

A081 , CURRENT <a) CFA , 

HERE VOC-LINK @ , VOC-LINK 1 
DOES> 

2+ CONTEXT '. ; IMMEDIATE 


DEFINITION/COMPILE TIME action of VOCABULARY (Sequence 1/2): ( - ) 


NOTE: The act of compiling all of the words in VOCABULARY 's flowchart is the definition time (Sequence 1) activity of 

VOCABULARY . The words between <BUILDS and DOES> are the compile time (Sequence . 2) activity of VOCABULARY . The words 
between DOES> and ;S are the execution time (Sequence 3) action of VOCABULARY. 


DOCOL 


<BUILDS 



<BUILDS will be 
executed when 
VOCABULARY is 
executed. This will be 
during a future 
compilation time when 
VOCABULARY is 
creating a new 
vocabulary definition. 
All words following (up 
to DOES> ) will be 
executed at this future 
compilation time in 
order to create 
the vocabulary 
definition. 


LIT 

A081H 


CURRENT 



riel 


Create the Pseudo Name l 

I lOIU, 


Set up for , . This is 
the Pseudo Name Field 
value. 


Create a Pseudo Name 
Field entry as the 
first entry in the 
Parameter Field. 


< Create the "Vocabulary! 
Link Field". j 


CURRENT contains the 
address of the parent's 
"Vocabulary Link 
Field". 
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@ 


CFA 


HERE 


VOC-LINK 


1 


VOC-LINK 



Fetch the address of 
the parent's Vocabulary 
Link Field. 


This is an incorrect 
usage of CFA. The 
intent here is to 
calculate the address 
of the Pseudo Name 
Field given the address 
of the Vocabulary Link 
Field. Since the Pseudo 
Name Field is two bytes 
long, CFA works; 
although, it is 
misleading. 


Create the Vocabulary 
Link Field. This field 
is initialized to point 
to the Pseudo Name 
Field of the parent 
vocabulary. 


J Create the Chrono-1 
1 logical Link Field, j 


L 




Set up for 1 . Get the 
address of the Chaining 
Link Field of the 
definition being 
created so it can be 
used to update 
VOC-LINK . 


Set up for (a) . 
VOC-LINK contains the 
address of the 
previously created 
vocabulary Chrono¬ 
logical Link Field. 


Set up for ,. Get the 
contents of VOC-LINK . 


Create the Chrono¬ 
logical Link Field by 
storing the contents of 
VOC-LINK into the 
dictionary/definition. 


Set up for I . 


DOES> 



Stuff VOC-LINK with 
the address of the 
Chronological Link Field 
just created. 


j Create the run time 
code for the word 
VOCABULARY. 


< CG 

b 


*} 


Only one copy of the 
following code will 
exist in the system. 

It is compiled into the 
VOCABULARY 
definition after the 
DOES> . 

Any definitions 
subsequently created 
via VOCABULARY will 
contain a pointer which 
points to this code. 


EXECUTION TIME action of VOCABULARY (Sequence 3): ( - ) 


NOTE: Since VOCABULARY uses <BUILDS and DOES> to create 
a definition, the execution time portion of VOCABULARY is 
simply the code following DOES> . 


2 + 


CONTEXT 



Aim at the Vocabulary 
Link Field. The 
execution time portion 
of DOES> places the 
Parameter Field Address 
(PFA) of the vocabulary 
definition being 
executed onto the top 
of the parameter stack. 
i.e., It points to the 
Pseudo Name Field. 
Adding 2 aims at the 
Vocabulary Link Field. 


Set up for ! . 


The run time action of 
VOCABULARY is to 
stuff CONTEXT with 
the address of the 
Vocabulary Link Field 
of the named 
vocabulary. 
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}S 


IMMEDIATE 


(Run time portion of 
; .) Stop interpret¬ 
ing this definition 
and return to the 

calling procedure. 


Set the precedence 
bit of the preced¬ 
ing definition so it 
will be executed at 
compile time and not 
compiled into the 
definition being 
comDiled. 


VOCABULARY is a 
defining word and 
therefore must execute 
during compilation 
(Sequence 2) so that it 
can compile other 
definitions. 





w 


w 

W is a pointer used by FORTH's "threading" words. It plays an important role in such words as NEXT , ;S , DOCOL (the execution time 
portion of :), etc. 

W generally serves as a pointer to the Code Field of the definition currently being executed. NEXT jumps indirectly "through" this 
pointer to execute the Code Field procedure* 

W is not a true FORTH word. It is not a variable. It is a logical entity and may be physically kept in registers or memory or whatever 
depending upon the exact system implementation. 

In 8080 fig-FORTH Version 1.1, W is contained in register pair DE. 

Refer to NEXT , : , and ;S . 
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WARNING ( — data address ) 

WARNING is a user variable that contains a value used in determining the following: 


WARNING 


1. Whether the system ABORT's or QUIT's via the word ERROR . 

2. The format of messages output via the word MESSAGE . 

When ERROR executes and WARNING contains a negative value, (ABORT) will occur and execution will stop. (ABORT) is intended to be 
a user defined error handling procedure. 

When ERROR executes and WARNING contains a non-negative value (i.e., zero or positive value), MESSAGE will execute and then a 
QUIT will stop execution. 

When MESSAGE executes and WARNING contains a zero, only the message number will be output. (This allows the system to operate 
without a disk.) 


When MESbAut. executes and WARNING is non-zeru, text messages will be output using Line G of Screen 4 of Drive Q as a base location* 


WARNING is initialized by COLD during system startup with data from the origin parameter area. 

The user variable WARNING is stored as a 16-bit single precision value. When in memory, the high and low order bytes may be switched 
depending upon the processor used. 


* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable WARNING . 


Refer to MESSAGE , ERROR , and USER . 

FORTH-79: There is no FORTH-79 equivalent for WARNING . 



How WARNING is Used 
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WHILE 

WHILE 


COMPILE TIME (Sequence 2): ( loop address \ 1 — loop address \ l\ offset location \ 4 ) 

EXECUTION TIME (Sequence 3): ( truth flag — ) 

WHILE is a compiler word and therefore exhibits two different sets of actions; those actions at compile time and those at execution 
WHILE is used as the beginning of the "true portion/loop body" of a BEGIN-WHILE-REPEAT structure in the form: 


BEGIN "set exit conditional" 


WHILE "true portion/loop body" 
REPEAT 

This is known as a "pre-test" loop. 


It is important to note that when using this structure it is possible for the loop to terminate before the "Iood 
once. This is because the exit condition is tested before executing the "loop body", i.e., The loop will continue 

i<5 tri ip ' ^ 


body" is executed even 
"while" the boolean flag 


If the "loop body" must always be executed at least once (a post-test loop), the structure BEGIN-UNTIL should be used instead. 

Il'rnmSiilir ^equence 2) action of WHILE is almost identical to that of IF . So close, in fact, that an IF is executed within WHILE 
at compile time. (This IF is executed when compiling a definition .containing WHILE , at Sequence 2; not during compilation of WHILE , 

fnr thp W nRRA h MrM b - ee ? at Sa ^ ence ^ A 0BRANCH ls compiled into the definition and the location immediately following is reserved 
the 0BRANCH s forward branch offset. The address of that location is placed on the stack so that the following REPEAT can 
calculate and store the appropriate branch offset into the reserved location. y 

To provide compiler security the value 4 is left on the stack. (The 2 left by IF is incremented by 2.) REPEAT can then check for the 
REPEAT ° f V3lUe 11113 pr ° Vldes a secure (but not foolproof) method of checking for an unmatched WHILE and 


The execution time (Sequence 3) action of WHILE is to control exit from the loop. This is accomplished via the compiled OBRANCH . A 
(i°p in J 'I ^\ nPU L a S aC ^° n iS , taken dased on this fla 9‘ If flag is true (non-zero), the true portion of the structure is executed 
REPEAT W ’ ^ the fIaQ 13 ° ’ the °° P WlU be exited and contro1 wil1 be passed to the word immediately following 


BEGIN-WHILE-REPEAT structures must be used within a colon definition. 

Any amount of processing may be performed between the BEGIN and the WHILE as long as the final result is a boolean flag. 

Note that WHILE is an IMMEDIATE word. This means that its precedence bit is set, and it will therefore execute at compile time. 
(NUMBER) is an example of a word which uses WHILE . 

COMPILE TIME (Sequence 2): 


At entry - The top of the parameter stack contains the 16-bit signed single precision value 1 used for compiler security. 
The second stack entry contains the 16-bit entry point address of the first word following BEGIN . These parameters are 
provided by BEGIN . 

At exit - The top of the parameter stack contains the 16-bit signed single precision value 4. This value is used by REPEAT 
for compiler security to ensure that the BEGIN-WHILE-REPEAT structure contains a WHILE. The second stack entry 
contains the 16-bit address of the reserved OBRANCH offset location created by the IF inside of WHILE . The third stack 
entry contains the i6-bit signed single precision value 1 left by the BEGIN to ensure that the structure is started with a 
, GIN i* Th f ™rth stack entry contains the 16-bit address of the first location following the BEGIN statement (i.e., the 
loop address). These parameters are used by REPEAT . 

EXECUTION TIME (Sequence 3): 


* At entry - The top of the parameter stack contains a 16-bit signed boolean truth flag. 

* At exit - No parameters. 


LIKELY ERROR MESSAGES: 


COMPILATION ONLY (11H) — This word may only be used within a colon definition. 


WHILE is a high level colon definition. 

Refer to BEGIN , REPEAT , OBRANCH , and UNTIL . 

FORTH-79: The FORTH-79 equivalent for WHILE is WHILE . 

Definition: : WHILE ( loop address\ 1 -- loop address\l\ offset\4 ) 

[COMPILE] IF 2+ ; IMMEDIATE 


( compile time ) 



COMPILE TIME action of WHILE (Sequence 2): 

( loop address \ 1 — loop address \ 1 \ offset location \ 4 ) 


EXECUTION TIME action of WHILE (Sequence 3): 
( truth flag — ) 


DOCOL 


[COMPILE] 


F 


2 + 


;S 


IMMEDIATE 



Since IF is an 
IMMEDIATE word, 
[COMPILE] must be 
used to compile it into 
the definition. 
(Otherwise it would 
execute instead of being 
compiled.) [COMPILE] 
is only used to "compile" 
F into WHILE (at 
Sequence 1) and does 
not exist in WHILE's 
definition when WHILE 
is executed at compile 
time (Sequence 2). 


IF will be executed at 
a later compile time 
(Sequence 2) when 
WHILE is executed. 


This increments the 2 
left by IF to provide 
compiler security for 
the following REPEAT 


WHILE is a compiler 
word and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 


BEGIN 

:<W)- 

_i 


Set up boolean truth 
flag on the top of 
the parameter stack. 



execution time portion 
of REPEAT . 

Branch back to 
BEGIN . 



V 


This is the entry point 
for the BEGIN part of 
this loop structure. 
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WIDTH 


WIDTH ( — data address ) 


oVthr^meFtet/^rvaiue mavT^nTT T?",?' f a «<=ters saved in the compilation of a definition name (i.e„ the 
determine how many characters to compile into the NamT Fiel°d. The "nqSbyte ifnoUncluTed fieETwfiif sp^cTeTby WJH 'l* 

WIDTH is initialized by COLD durina svstem startim wii-h Hota _..__ 

j - -r - '“-"'i »-• iw ui lym jjoiaiiiciBr area. 


The user variable WIDTH is stored as a 16-bit single precision value, 
depending upon the processor used. 


When in memory, the high and low order bytes may be switched 


* At entry - No parameters. 

* At exit - The top of the parameter stack contains the address of the user variable WIDTH . 
Refer to CREATE , and USER . 

FORTH-79: There is no EORTH-79 eguivalent for WIDTH . 
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WORD 

WORD ( delimiter value — ) 

WORD parses one word from the input stream. For example, WORD reads text characters from the input stream until the 
specified delimiter character is encountered. 

Text characters are transferred from the input stream to memory starting at the next available dictionary location ( HERE ). 

WORD leaves the character count of the text string in the first byte of the string. The string is terminated with one or more 
blanks. 

Leading delimiter characters are ignorea ana noc cransrerrea tu memury. ■ imuny ueunmcio a.e ^ 7 . 

Ascii "nulls" (00H) are treated as unconditional delimiters. Refer to ENCLOSE for specific conditions and their results. 

The source of the input stream is determined by the value of the user variable BLK . If BLK is zero, text is input from the 
terminal buffer. If BLK is non-zero, the value specifies the disk block to be used as input. 

* At entry - The top of the parameter stack contains a 16-bit value. The low order 8-bits contains an 8-bit ascii character 
to be used as a delimiter. The high order 8-bits should be zero. BLK contains a value used in determining input stream 
source. 

* owif M No parameters on the stack. However, HERE points to the beginning of the parsed word. 


WORD is a high level colon definition. 


Refer to ENCLOSE , BLK , and IN . 

FORTH-79: The FORTH-79 eguivalent for WORD is WORD . Note that FORTH-79 reguires that WORD return the beginning address of 
the parsed string. 


Definition: 




BLK 


@ 


IF 


WORD ( delimiter — ) 

BLK |a) IF 

BLK la) BLOCK 
ELSE 

TIB fa) 

THEN 

IN la) + SWAP ENCLOSE HERE 22 BLANKS 
IN +1 OVER - >R R HERE Cl 
+ HERE 1+ R> CMOVE ; 












@ 


THEN 



IN 


§ 


SWAP 


ENCLOSE 


HERE 


Replace the address 
on the top of the 
parameter stack with 
the memory contents 
of that address. 


Pick up the address of 

LIT 

Place the 

literal 

the terminal buffer 

22H 

value 22H onto the 

area. 


top of the parameter 



stack. 

1 

— 


— 

— 


Place the address of 
the user variable IN 
onto the top of the 


Entry point from the 
"true portion" of the 
previous IF (branched 
around ELSE portion). 


Now have an address on 
the stack which points 
to the input stream 
data. 

Now calculate the 
beginning address of 
the next token (i.e., 

IN + buffer address). 


Set up for (a) . IN is 
used as a character 
pointer into the 


BLANKS 


IN 


| parameter stack. 

buffer. IN is set to 0 



by QUERY or LOAD 
or --> (all of which 
eventually use 

WORD ). 

Replace the address 
on the top of the 
parameter stack with 
the memory contents 
of that address. 

Pick up the current 
offset into the input 
text buffer. 




Replace the top two 
parameter stack 
values with their 
total. 

Buffer address + offset 
= beginning address of 
string to be "read" in. 




Swap the top two 
values on the 
parameter stack. 

Set up delimiter and 
text address for 
ENCLOSE. 


jparse a tokemj 


OVER 


Scan text and 
determine offsets to 
beginning and end of 
delimited string, 
and offset to first 
non-parsed 
character. 


Parse one token (i.e., 
find one word) out of 
the input buffer. 


>R 


Fill destination area 
with blanks. 


3 


Place the address of 
the next available 
dictionary location 
on the top of the 
parameter stack. 


Set up for BLANKS. Set 
up to fill the parsed 
word's destination area 
with blanks. 


HERE 


Place the address of 
the user variable IN 
on the top of the 
parameter stack. 


Increment the 16-bit 
contents of the 
specified memory 
address by the 
specified signed 
16-bit value. 


Copy the second 
parameter stack 
value onto the top 
of the parameter 
stack. 


Subtract the top 
stack entry from the 
second stack entry 
and replace the two 
values with their 
signed difference. 


Remove the top value 
of the parameter 
stack and place it 
onto the top of the 
return stack. 


Copy the value on 
the top of the 
return stack onto 
the top of the 
parameter stack. 


Place the address of 
the next available 
dictionary location 
onto the top of the 
parameter stack. 


Fill memory with the 
specified number of 
ascii blanks 
starting at the 
specified address. 


Set up for BLANKS. 
Blank 34 bytes. 


Initialize destination 
area with 34 blanks. 
This is how the "string 
is terminated with one 
or more blanks". 


Increment the character 
pointer, IN to the 
beginning of the next 
token. 


Set up for +1 


Add the total string 
length up to the first 
non-parsed character 
(left on stack from 
ENCLOSE ) to IN. Aim 
IN at the next string to 
be parsed in the input 
buffer. 

I Calculate and create I 

j the length byte. f 

Set up for - . Place 
offset to beginning of 
parsed word onto the 
top of the parameter 
stack. 


End of parsed word - 
beginning of parsed 
word = length of parsed 
word. 


Temporarily save parsed 
word length. 


Set up for Cl . Get 
word length so can 
store it in length 
byte. 


Set up for Cl . HERE 
aims at length byte 
now. 
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Cl 


+ 


HERE 


1 + 


R> 


CMOVE 


;s 
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X 


X ( — data address ) 

X is a pseudonym for NULL . 

Refer to NULL . 

FORTH-79! There is no FQP.TH-79 equivalent for X 
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XOR 


XOR ( valuel \ value2 — logical result) 

XOR (pronounced "Exclusive-OR" or "X-OR" or "X-O-R") performs a bit-wise logical Exclusive-OR function on the two values on the top 
of the stack; and replaces them with their logical result. 

TOGGLE is an example of a word which uses XOR . 

* At entry - The top two stack values contain 16-bit logical values to be Exclusive-ORed. 

* At exit - The top of the stack contains the 16-bit logical result. 

XOR is a low level code primitive. 

FORTH-79: The FORTH-79 equivalent for XOR is XOR . 



HPUSH Push result onto top of 


stack. 

NEXT 
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[ (-) 


[ (pronounced "left-bracket") is used to suspend compilation within a colon definition. The words that follow [ are executed, not 
compiled. Compilation is resumed via the ] (resume compilation) command. 

An example of the use of [ can be found in ;CODE where the assembly language code following ;CODE must be executed and not 
compiled. [ is used within ;CODE to set STATE to 0 (i.e., stop compiling and start interpreting). The assembly language mnemonics 
following ;CODE are then interpreted which then causes machine code to be compiled into the definition being created. 

QUIT uses [ to set the system back into interpretation state. 

The effect of [ is to put a 0 into the user variable STATE . 

Note that [ is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 

* At entry - No parameters. 

* At exit - No parameters. 

[ is a high level colon definition. 

Refer to ] , INTERPRET , ;CODE , and LITERAL . 

FORTH-79: The FORTH-79 equivalent for [ is [. 

Definition: : [ ( —) 

0 STATE 1 ; IMMEDIATE 


DOCOL 


0 


STATE 


;S 


IMMEDIATE 



Set up for I . 


Set up for ! . STATE 
is referenced by 
INTERPRET to 
determine whether to 
compile or execute 
a word. 


Store 0 into STATE . 
Set system to interpret 
mode. 


[ is a compiler word 
and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 
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[COMPILE] 


[COMPILE 3 ( — ) (Word to compile must be the next word in the input stream) 

[COMPILE] (pronounced "bracket-compile") forces the compilation of the immediate word following [COMPILE] 

[COMPILE] forces the next input stream word to always be compiled. (i.e., The input^stream word immediately 
compiled into the dictionary and is not executed.) This is the only way immediate words can be compue*. ^unng 
can execute at a later time (their Sequence 3). 

QUIT is an example of a word which uses [COMPILE ] . 

[COMPILE ] is the functional equivalent of: 

[ Stop compiling. 

' name Locate the specified definition in the dictionary. 


in the input stream. 

following [COMPILE] is 
Sequence 2) so that they 


Ct A Get the definition’s CPA . 


, Store the CFA into the dictionary. 

] Start compiling. 


* At entry - No parameters. The name of the definition to be compiled must immediately follow [COMPILE] in the input 
stream. 

* At exit - No parameters. 


LIKELY ERROR MESSAGES: 

? pronounced "HUH?" (0) — The word in question cannot be found in the dictionary. 

COMPILATION ONLY (11H) — This word may only be used within a colon definition. 

Note that [COMPILE] is an IMMEDIATE word. This means that its precedence bit is set and it will therefore execute at compile time. 


[COMPILE] is a high level colon definition. 

Refer to [ , COMPILE , ] , and INTERPRET . 

FORTH-79: The FORTH-79 equivalent for [COMPILE ] is [COMPILE ] . 

Definition: : [COMPILE ] 

-FIND 0= 0 7ERROR DROP CFA , 


0 


DOCOL 


-FIND 


0 = 


IMMEDIATE 



TERROR 


"Find" the dictionary 
address of the word 
that follows [COMPILE ] 
(in the input stream). 


{ Issue an error message 
if -FIND could not find > 
the word. I 

Set up for TERROR . 
Complement the truth 
flag left by -FIND so 
that it is in the 
format TERROR 
expects. 


DROP 









CFA 


;s 


IMMEDIATE 



Convert the PFA left by 
-FIND into the CFA of 
the word. 


Compile this address 
into the dictionary. 


[COMPILE ] is a 
compiler word and 
therefore must execute 
during compilation 
(Sequence 2) so that it 
can compile other 
definitions. 
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] (-) 


] 

] (pronounced "right-bracket") places the system into the compilation state. This word is normally used to resume compilation after [ 
was used to halt compilation. The effect of ] is to place a non-zero value into the user variable STATE . 

Note that STATE is set to COH and not just 01. This is done to save processing time in INTERPRET . Setting STATE to a non-zero value 
puts the system into compilation mode but, even in compilation mode, IMMEDIATE words must be executed and not compiled (e.g., 
compiler words). The purpose of using CuH, then, is to cause compilation of all but IMMEDIATE words. 

In fig-FORTH this works very simply. A definition is flagged as IMMEDIATE when the 40H bit (the "precedence" bit) in the length byte is 
set to 1. The most significant bit in the length byte is always set to 1 (the 80H bit). Additionally, the actual length of a name is always 
greater than 0. Just the logical combination of the precedence bit and the "beginning of Name Field bit" equals COH. Adding the name 
length always makes this value greater than COH because names cannot be 0 characters long. 

What INTERPRET does then, is compare the value of the length byte with the contents of STATE. Whether compilation or 
interpretation takes place is based on the following: 



STATE 


MODE 

CONTAINS 

ACTION 

Interpret 

0 

All words will have length bytes greater than 0 
and INTERPRET will execute the word. 

Compile 

COH 

IMMEDIATE words will have length bytes greater 
than COH and will be executed. 

Compile 

COH 

Words whose precedence bits are not set will be 
less than COH and will be compiled. 


In this way, IMMEDIATE words will be executed and non-IMMEDIATE words will be compiled. 

An example of a use of ] would be to resume compilation after stopping compilation with [, then calculating some value and leaving it 
on the stack for LITERAL : 


: AWORD-[ calculate value ] LITERAL 

: uses ] to set the system to compilation mode so the defined word can be compiled. 


* At entry - No parameters. 

* At exit -No parameters. 

] is a high level colon definition. 


FORTH-79; The FORTH-79 equivalent for ] is ] . 


Definition; 


DOCOL 


LIT 

COH 


STATE 


: ] ( - ) 

CO STATE 1 



IMMEDIATE 


Set up for I . 


Set up for ! . STATE 
is referenced by 
INTERPRET to 
determine whether to 
compile or execute 
a word. 


Set STATE to compile 
state. 


_-_I___ 

;S (Run time portion of 

;.) Stop interpret¬ 
ing this definition 
and return to the 
calling procedure. 


IMMEDIATE 


Set the precedence 
bit of this 
definition so it 
will be executed at 
compile time and not 
compiled into the 
definition. 


] is a compiler word 
and therefore must 
execute during compil¬ 
ation (Sequence 2) so 
that it can compile 
other definitions. 
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FORTH SYSTEM MESSAGES 
(Relative to Drive 0 Screen 4 Line 0) 


HEX 

DECIMAL 

MESSAGE 

DESCRIPTION 

0 

0 

? (pronounced "HUH?") 

The word in question cannot be found in the 
dictionary. 

1 

1 

EMPTY STACK 

More values have been removed from the parameter 
stack than were added. The stack pointer has 
backed up beyond the initial stack pointer location. 

2 

2 

DICTIONARY FULL 

The dictionary has grown into the Terminal Input 
Buffer. 

4 

4 

ISN'T UNIQUE 

The name of this definition already exists elsewhere 
in the dictionary. 

6 

6 

DISK RANGE? 

A disk access to a physically non-existent block 
number was requested. (Make sure you are not in 
base hex when you think you are in base decimal.) 

7 

7 

FULL STACK 

Too many values have been added to the parameter 
stack. The stack pointer has gone beyond its upper 
limit. 

8 

8 

DISK ERROR! 

An I/O error occurred while attempting to read or 
write to virtual I/O. (Make sure diskette is in the 
drive and the door is shut.) 

11 

17 

COMPILATION ONLY 

This word must only be used within a colon 
definition. 

12 

18 

EXECUTION ONLY 

The word must not be used while the system is in 
compile mode. 

13 

19 

CONDITIONALS NOT PAIRED 

There is some sort of problem with the pairing of 
conditionals within the definition being compiled. 

14 

20 

DEFINITION NOT FINISHED 

The position of the parameter stack pointer differs 
from what it was when this definition began 
compiling. Something is wrong wtih the definition. 

15 

21 

PROTECTED DICTIONARY 

The address of the definition being "forgotten" is 
less than the value stored in FENCE . Change the 
value in FENCE . 

16 

22 

USE ONLY WHEN LOADING 

This definition should only be used when loading. 

17 

23 

OFF CURRENT EDITING SCREEN 

Occurs when using fig-FORTH editor. 

18 

24 

DECLARE VOCABULARY 

CONTEXT and CURRENT are not aiming at the 
same vocabulary when attempting to FORGET . 
(The purpose of vocabularies is to limit the scope of 
a definition, so forcing both CONTEXT and 
CURRENT to be equal prevents inadvertently 
forgetting a definition.) 
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